home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / ccomp.zip / PCC.DOC < prev    next >
Text File  |  1988-12-01  |  168KB  |  4,450 lines
  1.  
  2.  
  3.  
  4.                                Personal C Compiler
  5.  
  6.                                     PCC 1.2b 
  7.  
  8.  
  9.                          A Product of C WARE CORPORATION
  10.  
  11.                       Copyright (c) 1988 C WARE CORPORATION
  12.                                All Rights Reserved
  13.  
  14.         PCC is a fully operational and tested C Compiler.  This is NOT 
  15.         cripple-ware.  As a reward for registration, you will receive a 
  16.         disk with several utilities to enhance the compiler:
  17.  
  18.         1. Clist -     reads C source files and produces a listing file 
  19.                        with a symbol cross-reference.
  20.  
  21.         2. Lib88 -     object code librarian.  Reads object files and 
  22.                        other library files and produces library files.
  23.  
  24.         3. Profile -   C program execution profiler.  Monitors program 
  25.                        execution and shows where time is spent in the 
  26.                        program.
  27.  
  28.         4. Xarray -    A library of memory access functions to use the 
  29.                        entire 640K RAM space.  With source.
  30.  
  31.         Registered users are also eligible to purchase several useful 
  32.         utilities to further enhance the capabilities of the compiler.  
  33.  
  34.  
  35.         1. The Legal Stuff
  36.  
  37.         This version of the documentation, software and copyright 
  38.         supersede all previous versions of PCC.
  39.  
  40.         PCC software copyright (C) 1988 by Mark DeSmet and C WARE
  41.         CORPORATION. All rights reserved.
  42.  
  43.         This document copyright (C) 1988 C WARE CORPORATION.  All rights 
  44.         reserved.
  45.  
  46.         Specifications subject to change without notice.
  47.  
  48.         Most of the hardware names in this manual are trademarks or trade 
  49.         names of specific manufactures.
  50.  
  51.         Legal Stuff                                         Page 2
  52.  
  53.  
  54.         1.1. License
  55.  
  56.         This PCC is NOT public domain or free software, but is being 
  57.         distributed as "shareware".
  58.  
  59.         PCC is copyright (C) 1988 by Mark DeSmet and C WARE CORPORATION.
  60.  
  61.         Non-registered users of this software are granted a limited 
  62.         license to make an evaluation copy for trial use on a private, 
  63.         non-commercial basis, for the express purpose of determining 
  64.         whether PCC is suitable for their needs.  At the end of this trial 
  65.         period of THIRTY DAYS you MUST either register your copy or 
  66.         discontinue using PCC.
  67.  
  68.         A PCC registration entitles you to use the program on any and all 
  69.         computers available to you, as long as you use the program on 
  70.         only one computer at a time with the following restriction:
  71.  
  72.         All users are granted a limited license to copy PCC only for the 
  73.         trial use of others.  This license does NOT include distribution 
  74.         or copying of this software package:
  75.  
  76.              1. In connection with any other product or service except as 
  77.                 noted below.
  78.              2. For general use within a company or institution.
  79.              3. Distribution in modified form. This license information 
  80.                 MUST be included, along with the full PCC documentation 
  81.                 and all PCC files as released by C WARE CORPORATION.
  82.  
  83.         Operators of electronic bulletin board systems (SYSOPS) are 
  84.         encouraged to post PCC for downloading by users.
  85.  
  86.         If you are the distributor of a public domain or user-supported 
  87.         software library, you may be distribute copies of PCC. A fee,
  88.         not to exceed $10.00 per disk, may be charged for copy service, 
  89.         handling and materials.  The files MUST be distributed in 
  90.         "archived" form so users may be able to adequately verify the 
  91.         integrity of the files.
  92.  
  93.         The additional utilities available to registered users shall NOT 
  94.         be distributed by any individual or organization other than C 
  95.         WARE CORPORATION.
  96.  
  97.         1.2. Support Policy
  98.  
  99.         The nature of this product and the pricing makes it necessary for 
  100.         us to NOT provide telephone support for users except as noted 
  101.         in the pricing schedule below.  We will have to refuse to answer 
  102.         questions unless you have registered the product AND paid for 
  103.         phone support.  Every attempt will be made to address questions 
  104.         left on our support BBS in an appropriate and timely manner. 
  105.         However, this support will be on a when-time-is-available basis 
  106.         and C WARE CORPORATION is NOT responsible to provide support in 
  107.         any form for non-registered or registered users.  Information 
  108.         will be posted on our support BBS when it becomes available as 
  109.  
  110.         Legal Stuff                                         Page 3
  111.  
  112.  
  113.         well as bug fixes or patches.  Upgrades to PCC will be made when 
  114.         appropriate to improve, enhance or correct the product.
  115.  
  116.         1.3. DISCLAIMER
  117.  
  118.  
  119.         The author has taken due care in preparing this manual and the 
  120.         programs and data on the electronic media accompanying this book 
  121.         including research, development, and testing to ascertain their 
  122.         effectiveness.  The author and the publisher make no expressed or 
  123.         implied warranty of any kind with regard to these programs nor 
  124.         the supplemental documentation in this book.  In no event shall 
  125.         the author or C Ware Corporation be liable for incidental or 
  126.         consequential damages in connection with or arising out of the 
  127.         furnishing, performance or use of any of these programs.
  128.  
  129.  
  130.         1.4. FOREIGN RESHIPMENT LIABILITY
  131.  
  132.         THIS LICENSE AGREEMENT IS EXPRESSLY MADE SUBJECT TO ANY LAWS, 
  133.         REGULATIONS, ORDERS OR OTHER RESTRICTIONS ON THE EXPORT FROM THE 
  134.         UNITED STATES OF AMERICA OF SOFTWARE, OR OF INFORMATION ABOUT 
  135.         SUCH SOFTWARE, WHICH MAY BE IMPOSED FROM TIME TO TIME BY THE 
  136.         GOVERNMENT OF THE UNITED STATES OF AMERICA.  NOTWITHSTANDING 
  137.         ANYTHING CONTAINED IN THIS AGREEMENT TO THE CONTRARY, YOU MAY NOT 
  138.         EXPORT, DIRECTLY OR INDIRECTLY, ANY SUCH SOFTWARE OR INFORMATION 
  139.         PERTAINING THERETO TO ANY COUNTRY FOR WHICH SUCH GOVERNMENT OR 
  140.         AGENCY THEREOF REQUIRES AN EXPORT LICENSE OR OTHER SUCH 
  141.         GOVERNMENT APPROVAL AT THE TIME OF EXPORT WITHOUT FIRST OBTAINING 
  142.         SUCH LICENSE OR APPROVAL.
  143.  
  144.         1.5. LIMITED WARRANTY                                                           
  145.  
  146.         PCC IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 
  147.         EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
  148.         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
  149.         PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF 
  150.         PCC IS WITH YOU.
  151.  
  152.         SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO 
  153.         THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU.  THIS WARRANTY GIVES 
  154.         YOU SPECIFIC LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS 
  155.         WHICH VARY FROM STATE TO STATE.
  156.  
  157.         C Ware does not warrant that operation of PCC will be 
  158.         uninterrupted or error free.
  159.  
  160.         1.6. LIMITATIONS OF REMEDIES
  161.  
  162.         If C Ware is unable to deliver a copy of PCC that is 
  163.         satisfactory, then you may obtain a full refund by returning all 
  164.         PCC materials and documantation within thirty days of delivery to 
  165.         you as evidenced by a copy of your receipt.
  166.  
  167.         Legal Stuff                                         Page 4
  168.  
  169.  
  170.         This refund is the entire extent of C Ware's liability and your 
  171.         exclusive remedy.
  172.  
  173.         IN NO EVENT WILL C WARE BE LIABLE TO YOU FOR ANY DAMAGES, 
  174.         INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR 
  175.         CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 
  176.         PCC EVEN IF C WARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
  177.         DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  178.  
  179.         SOME STATES DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY 
  180.         FOR INCIDENTAL OR CONSEQUENTAIL DAMAGES SO THE ABOVE LIMITATION 
  181.         OR EXCLUSION MAY NOT APPLY TO YOU.
  182.  
  183.         1.7. General
  184.  
  185.         This Agreement will be governed by the laws of the State of 
  186.         California.
  187.  
  188.         Should you have any questions concerning this Agreement, you may 
  189.         write to C Ware Corporation, PO Box 428, Paso Robles, CA 93447.
  190.  
  191.         YOUR CONTINUED USE OF PCC BEYOND THE THIRTY DAY TRIAL PERIOD, 
  192.         WITH OR WITHOUT REGISTRATION, ACKNOWLEDGES THAT YOU HAVE READ 
  193.         THIS AGREEMENT, UNDERSTAND IT AND AGREE TO BE BOUND BY ITS TERMS 
  194.         AND CONDITIONS.  YOU FURTHER AGREE THAT IT IS THE COMPLETE AND 
  195.         EXCLUSIVE AGREEMENT BETWEEN US WHICH SUPERSEDES ANY PROPOSAL OR 
  196.         PRIOR AGREEMENT, ORAL OR WRITTEN, ANY ANY OTHER COMMUNICATIONS 
  197.         BETWEEN US RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.
  198.  
  199.         1.8. TRADEMARKS
  200.  
  201.         MS-DOS is a registered trademark of Microsoft Corporation.
  202.         PC-DOS is a registered trademark of IBM Corporation.
  203.         Compaq is a registered trademark of Compaq Inc.
  204.         Tandy 1000 is a registered trademark of Tandy Corporation.
  205.  
  206.  
  207.         1.9. ORDERING INFORMATION
  208.  
  209.         A PCC registration licenses you to use the product on a regular 
  210.         basis.  Users need register only one version of PCC. Registration 
  211.         includes licensed use of all upgrades.  Registered users can 
  212.         always get the most current version of the program at a nominal 
  213.         fee ($8.00 as of this writing) by calling or writing C WARE 
  214.         CORPORATION.  The latest version will also be available on our 
  215.         support BBS at (805)-239-4834 and the below listed "official 
  216.         distribution BBSs":
  217.  
  218.         1. PYSMATIC BBS, Sunnyvale, CA  (408)-992-0372 
  219.  
  220.  
  221.  
  222.         If you purchased PCC through a distributor of public domain or 
  223.         user-supported software, you did NOT pay for the license.  The 
  224.         fee ($10.00 max per disk) was to cover the costs of copying the 
  225.  
  226.         Legal Stuff                                         Page 5
  227.  
  228.  
  229.         disk(s), the media and handling overhead.  You paid for the 
  230.         vendors service.
  231.  
  232.         Registration for PCC costs $30 and assumes you have already 
  233.         received a copy of the program from whatever source.  We will 
  234.         also send you the next major upgrade of PCC when it is released OR 
  235.         if you ask when you register, we will send you a certified copy of
  236.         the current version of the program, and you must download or send us 
  237.         $8.00 to get the next major upgrade. 
  238.  
  239.         1.10. Use by Educational Institutions
  240.  
  241.         Educational institutions wishing to use PCC for courses involving 
  242.         C MUST obtain a site license.  State or city operated 
  243.         institutions shall pay $10.00 per student using the program.  
  244.         Private or commercial institutions shall pay $15.00 per student 
  245.         using the program.  All reproduction of documentation and media 
  246.         shall be done by the licensed site institution.  The additional 
  247.         utilities offered to registered users may be purchased at 66% off 
  248.         for state or city operated institutions and 50% off for private 
  249.         or commercial institutions.    
  250.               
  251.         Students using the program via this method are NOT registered 
  252.         users and must register their copy as per the licensing agreement 
  253.         for an indivdual if they use the program after completion or 
  254.         termination of the course.
  255.  
  256.         1.11. Corporate, Business, Government and Commercial Use
  257.  
  258.         Corporate, business, government or other commercial uses of PCC are
  259.         PROHIBITED.  We offer an excellent C Development Package for such 
  260.         commercial users.  Please contact C WARE CORPORATION directly for 
  261.         information and pricing. The intent of PCC is to provide a low 
  262.         cost tool for persons interested in learning C or using C 
  263.         for non-commercial personal use.  If you find you wish to sell a
  264.         program developed with PCC, you must do the following:
  265.  
  266.              1. The program and documentaion must prominently indicate 
  267.                 the code was compiled with PCC, copyright 1988 by 
  268.                 Mark DeSmet and C Ware Corporation.
  269.  
  270.              2. Get written permission ( which is no big problem ) by 
  271.                 sending us a copy of the program as it is to be sold or 
  272.                 distributed.  A letter granting permission will be sent 
  273.                 promptly, if your package meets the requirements of 
  274.                 paragraph 1 above.
  275.  
  276.  
  277.                 ALL PRICES ARE SUBJECT TO CHANGE WITHOUT NOTICE.
  278.  
  279.         Legal Stuff                                         Page 6
  280.  
  281.  
  282.         You can also register/order your copy of PCC by phone, using your 
  283.         MasterCard or VISA.  Phone (805)-239-4620, 9:00 - 4:00 p.m. PST 
  284.         or PDT only.  Minimum credit card order is $10.
  285.  
  286.         Sorry, C.O.D. orders will NOT be accepted.
  287.  
  288.         ORDERS OUTSIDE THE US: Please use your Mastercard or VISA when 
  289.         ordering,  or send checks drawn on US banks in US dollars.  All 
  290.         checks must have US bank magnetic routing symbols.  Please 
  291.         include an additional $5 to cover postage on orders to be sent 
  292.         outside of the US.
  293.  
  294.         Full-time students can apply a 10% discount on all prices. You 
  295.         MUST include your a photo-copy of your most recent registration 
  296.         slip and student ID card.
  297.  
  298.         PRICE SCHEDULE AND INFORMATION ( November 1988 )
  299.  
  300.              1. Individual Registration              -        $30.00
  301.                 - Copy of program sent if requested
  302.                 - Utility package sent automatically
  303.  
  304.            *** Below items only available to registered users. ***
  305.  
  306.              2. Editor                               -        $15.00
  307.                 - With object code
  308.  
  309.              3. Debugger                             -        $15.00
  310.  
  311.              4. MS DOS Linker compatability utility  -        $ 8.00
  312.  
  313.              5. Special utilities package            -        $ 8.00
  314.  
  315.              6. Five phone support calls (5-min).    -        $15.00
  316.                 - Total 25 minutes of help time
  317.  
  318.          
  319.  
  320.         NOTES:
  321.           
  322.              1. The above prices include CA sales tax.
  323.  
  324.              2. Sorry, we do not have a printed manual available.
  325.  
  326.              3. For fastest service please send Money Order or use Visa 
  327.                 or MasterCharge.  We must wait 10 days for personal 
  328.                 checks to clear.
  329.  
  330.              4. Please allow 30 days for delivery.  Money order, Visa and 
  331.                 MasterCharge should ship in two(2) working days but 
  332.                 things do get hectic at times.  Drop us a line if you 
  333.                 haven't received your order in 15 days.
  334.  
  335.              5. Please use the form in appendix C to order.
  336.  
  337.         Preface                                             Page 7
  338.  
  339.  
  340.         2. Preface
  341.  
  342.  
  343.         The PCC package would not exist but for the tireless work of 
  344.         L. B. Neal.  He has called us, badgered us, sent us manuals and 
  345.         materials, jumped up and down about the virtues of Shareware, and 
  346.         in general demanded that we create the personal C compiler, PCC.
  347.  
  348.         The PCC package owes everything else to the incredible work of 
  349.         Mark DeSmet.  At a time when most programmers couldn't spell C, 
  350.         Mark wrote a compiler, assembler, linker and library for not one 
  351.         operating system, but two.  The fact that it is still the fastest 
  352.         C compiler in the current benchmarks further attests to Mark's 
  353.         skills.
  354.  
  355.         This manual describes the C Ware Personal C Compiler for the IBM-
  356.         PC personal computer and the other MS-DOS based personal 
  357.         computers.  It is based on the DeSmet C Development Package.  If 
  358.         you are unfamiliar with the C language or UNIX, the book The C 
  359.         Programming Language  by Brian Kernighan and Dennis Ritchie is 
  360.         available.  If you plan on coding in assembly language, it is 
  361.         advisable to get a manual on the Intel 8086 microprocessor.   
  362.         Books such as Intel's ASM86 Language Reference Manual or The 8086 
  363.         Family User's Guide are good choices.  These manuals fully 
  364.         describe the architecture and the instruction set of the 
  365.         8086/8088 family of microprocessors.
  366.  
  367.         An Introduction to PCC                              Page 8
  368.  
  369.  
  370.         3. An Introduction To PCC
  371.             
  372.         Now that we made it through all of the formalities lets take a 
  373.         look at what PCC contains.
  374.  
  375.              PCC is a fast powerful C compiler.  It is fully compatable 
  376.              with code written for DeSmet Ver: 2.51. Code for earlier 
  377.              versions of DeSmet should work with minimal adjustment.
  378.  
  379.              This compiler is NOT full of bells and whistles it just 
  380.              makes fast tight compact programs.
  381.  
  382.              Some of the terms and conventions of PCC are a bit different 
  383.              from those in books on the C language, so we will quickly run
  384.              through the terms used in PCC.DOC.
  385.  
  386.              TEXT OR BOOK NAME        PCC NAME         COMMENT
  387.              -----------------        --------         -------
  388.              LINK                     PCCL             Builds .EXE file
  389.  
  390.              filename.obj             filename.o       Basis for .EXE file
  391.  
  392.              filename.asm             filename.a       Assembly source file
  393.  
  394.              MASM or ASM              PCCA             8088/8086 Assembler
  395.  
  396.              CC or CPP                PCC              Main Compiler 
  397.                                                        (First Pass)
  398.              CC1                      PC2              Compiler Second Pass
  399.  
  400.         3.1. Using Text, Book, Magazine or Download source code
  401.  
  402.         There are many C compilers.  There are also many variations of
  403.         interpretation of what C syntax should be.  And then there are
  404.         the extensions to support I/O, machine specific functions, etc.
  405.         Source NOT written for PCC or DeSmet Ver: 2.51 may need minor
  406.         adjustments to be accepted by the PCC compiler and run properly.
  407.  
  408.         In fact, finding, compiling and modifying source code is an 
  409.         excellent way to learn any language or compiler.  Just be careful 
  410.         not to adopt bad habits from exposure to poorly written code.
  411.  
  412.  
  413.         *****************************************************************
  414.  
  415.         CAUTION: PCC will accept any valid code you supply to it, as will 
  416.         any compiler.  The code may well be valid, but the result of the 
  417.         code could be dangerous to the health and safety of your 
  418.         computer, monitor or contents of your Hard Drive or floppies
  419.         ( and it WILL be at one time or another ).  Guard and maintain 
  420.         up-to-date copies of all files on your system.  If your program or 
  421.         the compiler starts to act erraticly: i.e. screen goes blank, funny 
  422.  
  423.         An Introduction to PCC                              Page 9
  424.  
  425.  
  426.         video display, noises from hardware, or any strange unexpected 
  427.         actions., IMMEDIATELY TURN OFF THE POWER to the computer and 
  428.         investigate carefully after you have the system rebooted.
  429.  
  430.         ******************************************************************                   
  431.  
  432.         THE REST IS UP TO YOU
  433.  
  434.         C is a powerful and useful language, we hope you find PCC a help 
  435.         to your learning and use of the C language.
  436.  
  437.         Your comments and suggestions on how to improve our product are 
  438.         welcome.
  439.  
  440.         Enjoy your adventure into the land of C and we hope PCC helps you
  441.         in your computing.
  442.  
  443.         3.2. Getting Started
  444.  
  445.         First things first.  Copy all of the files from the distribution 
  446.         disk onto a set of working floppy diskettes or hard disk.  The 
  447.         package is not copy-protected so the MS-DOS copy command can be 
  448.         used to copy the files.  The package is distributed on a single 
  449.         double-sided (360KB) diskette.  The distribution diskette should 
  450.         never be used, it should be kept as the backup copy of PCC.
  451.  
  452.         Lets make sure the compiler files are intact.  A source program 
  453.         called DUMP.C has been provided in this package.  Place the files 
  454.         from PCC12B.ARC in a directory of your choice or on floppy disks 
  455.         per the later documentation.  To compile DUMP.C enter
  456.  
  457.              >PCC DUMP
  458.  
  459.         This will compile DUMP.C into an object module DUMP.O.  To link 
  460.         DUMP.O with the required library functions in PCCS.S enter
  461.  
  462.              >PCCL DUMP
  463.  
  464.         This will produce a file DUMP.EXE.  To run DUMP.EXE enter
  465.  
  466.              >DUMP DUMP.C
  467.  
  468.         This will produce a hex and ascii dump of DUMP.C on your screen.  
  469.         If DUMP runs correctly, then the compiler should be in good 
  470.         working order.
  471.  
  472.         3.3. PCC Files
  473.  
  474.         The package is distributed as a compressed file -- PCC.ARC -- so 
  475.         that integrity checks may be run.  PCC.ARC contains the following 
  476.         files:
  477.  
  478.         BUF128.A       Source code for 128 byte type-ahead TSR.
  479.         BUGS!.EXE      Arcade game (use 'BUGS!   c' for color displays).
  480.         DUMP.C         Source code for hex file display utility.
  481.  
  482.         An Introduction to PCC                              Page 10
  483.  
  484.  
  485.         EXEC.O         The Exec() and Chain() functions.
  486.         LATER.C        Source code for a file modification date checking 
  487.                        program.
  488.         LIFE.C         Source code for the game of Life.
  489.         MATH.H         Include file for the Standard Math package.
  490.         PC2.EXE        The second pass of the C compiler.
  491.         PCC.DOC        This file
  492.         PCC.EXE        The first pass of the C compiler.
  493.         PCC7.S         The standard C function library with 8087 support.  
  494.                        To use this library, rename it to PCCS.S.
  495.         PCCA.EXE       The assembler and third pass of the C compiler.
  496.         PCCL.EXE       The object file linker.
  497.         PCCS.S         The standard C function library with software 
  498.                        floating-point support.
  499.         PCIO.A         Source code for the PC screen functions.
  500.         RAM.COM        RAM Disk driver for DOS 2.0 and later operating 
  501.                        systems.
  502.         SETJMP.H       Include file for the setjmp()/longjmp() functions.
  503.         STDIO.H        Include file for the Standard I/O package.
  504.  
  505.         3.4. Basic System
  506.  
  507.         The minimum files you need from PCC.ARC are PCC.EXE, PC2.EXE, 
  508.         PCCA.EXE, PCCL.EXE and PCCS.S.  The files STDIO.H and MATH.H 
  509.         contain useful declarations.
  510.  
  511.         If you are developing in a directory other than the one that 
  512.         contains the PCC files, be sure to set the PATH environment 
  513.         variable to include the PCC directory.
  514.  
  515.         3.5. Setting Up DOS 2.xx, 3.xx, ...
  516.  
  517.         For systems utilizing DOS 2.x or later versions of the operating 
  518.         systems, make sure that the ASCII text file CONFIG.SYS exists on 
  519.         your boot disk.
  520.           
  521.         The file must contain the line:
  522.  
  523.                 FILES=20
  524.  
  525.         since PCC supports 20 open files Q stdin, stdout, stderr, and 17 
  526.         other files.  The default number of eight is insufficient for the 
  527.         PCCL program.
  528.  
  529.         If there is enough memory available, add the line:
  530.  
  531.                 BUFFERS=20
  532.  
  533.         to improve file performance in the operating system.  512 bytes 
  534.         are allocated for each buffer specified.
  535.  
  536.         An Introduction to PCC                              Page 11
  537.  
  538.  
  539.         3.6. RAM DISK
  540.  
  541.         If you have a system with more than 256 kilobytes of memory, then 
  542.         the Ram Disk driver RAM.COM can be used to create an  extremely 
  543.         fast disk.  To add a Ram Disk, copy the RAM.COM file from the 
  544.         distribution diskette to the system disk and add the line:
  545.  
  546.                 DEVICE=RAM.COM   n
  547.  
  548.         to the CONFIG.SYS file.  The parameter, n, is a decimal number 
  549.         from 32 to 650 indicating the size of the Ram Disk.  The value is 
  550.         specified in units of one kilobyte (1024).  
  551.  
  552.         Re-boot the system to install the Ram Disk.  The drive letter 
  553.         used for this 'disk drive' is dependent on the configuration of 
  554.         the system.  DOS will install the Ram Disk at the first free 
  555.         device "slot".  For an IBM PC with two floppies, this will 
  556.         probably be drive C:.  For an XT, it will probably be drive D:.  
  557.         Sanyo 550/5 reserves the first four slots for its floppies, so 
  558.         the Ram Disk is drive E:.  To find where DOS has installed the 
  559.         Ram Disk, use
  560.  
  561.                 chkdsk x:
  562.  
  563.         where x takes on the values c, d, ....  You will get either a 
  564.         disk error, or a return showing the size of the Ram Disk.  Once 
  565.         you find it, the Ram Disk will always be the same until you add 
  566.         other device drivers before it in the CONFIG.SYS file.
  567.  
  568.         3.7. Completion Codes
  569.  
  570.         The PCC, PCCA, and PCCL programs set the completion code to:
  571.  
  572.                  zero  if no warnings or errors occurred,
  573.                  one  if warnings were issued, and
  574.                  two if errors occurred.
  575.  
  576.         Batch files can take advantage of these values to stop execution 
  577.         or otherwise handle these exceptional cases.
  578.  
  579.         The following batch file will stop on a PCC or PCCL error:
  580.  
  581.              PCC %1
  582.              if errorlevel 1 goto stop
  583.              PCCL %1
  584.              if errorlevel 1 goto stop
  585.              %1
  586.              :stop
  587.         More complicated development situations can be handled with the 
  588.         program LATER which is supplied in source form in the file 
  589.         LATER.C.  LATER takes a list of filenames as arguments.  It sets 
  590.         the errorlevel to one if the last file does not exist or if the 
  591.         last file has an earlier modification date than any other file in 
  592.         the list.  It can only be used on systems with a battery backup 
  593.         clock or where users are careful about setting the date and time 
  594.  
  595.         An Introduction to PCC                              Page 12
  596.  
  597.  
  598.         when the system is brought up.  Assume a program is composed of 
  599.         the files moda.c, modb.c, modc.c and the include file mod.h.  The 
  600.         following .BAT file can be used to regenerate the program 
  601.         whenever a module changes:
  602.  
  603.              later moda.c mod.h moda.o
  604.                   if errorlevel 1 PCC moda
  605.                        if errorlevel 1 goto stop
  606.              later modb.c mod.h modb.o
  607.                   if errorlevel 1 PCC modb
  608.                        if errorlevel 1 goto stop
  609.              later modc.c mod.h modc.o
  610.                   if errorlevel 1 PCC modc
  611.                        if errorlevel 1 goto stop
  612.              later moda.o modb.o modc.o mod.exe
  613.                   if errorlevel 1 PCCL moda modb modc -omod
  614.              :stop
  615.  
  616.         This provides a service similar to the UNIX MAKE program.  Only 
  617.         those files that need to be compiled will be compiled.
  618.  
  619.         PCC -- The Personal C Compiler                      Page 13
  620.  
  621.  
  622.         4. PCC -- The Personal C Compiler
  623.  
  624.         4.1. Introduction
  625.  
  626.         PCC is the C compiler for the 8088/8086 family of 
  627.         microprocessors.  It accepts C source programs as input and 
  628.         produces object files. The model employed by the compiler 
  629.         efficiently utilizes the 8088/8086 architecture but limits a 
  630.         program to 64KB code and 64KB of data.
  631.  
  632.  
  633.         Invocation
  634.  
  635.            PCC <filename> [options]
  636.  
  637.         <filename> is the name of the file containing the C source. If it 
  638.                    does not include an extension, the extension '.C' is 
  639.                    assumed.
  640.  
  641.         Options: The case of the option is not significant. Each option 
  642.         should be separated from other options by blanks.  Options may be 
  643.         preceded with the dash (-) character.
  644.  
  645.         A          - assembly output.  This option indicates that the 
  646.                    compiler should produce an assembly language source 
  647.                    file instead of an object file.  The name of the 
  648.                    assembly language file will be the same as the name of 
  649.                    the source file but will have the extension '.A'.
  650.  
  651.         D<name>    - compiler drive specification.  The compiler assumes 
  652.                    that the files PC2.EXE and PCCA.EXE are in the 
  653.                    default directory on the current drive.  This option 
  654.                    is used to inform the compiler that the files are on a 
  655.                    different drive.  For example, if the compiler is on 
  656.                    drive 'M', then the option 'DM' is needed.
  657.  
  658.                    Under MS-DOS 2.0 and later versions of the operating 
  659.                    system, this option is rarely  needed as the system 
  660.                    PATH variable is also used to find the other passes of 
  661.                    the compiler.
  662.  
  663.         I<name>    - include path name.  This option overrides the 
  664.                    default drive/directory for files included with the 
  665.                    #include control. The directory name must end with a 
  666.                    trailing backslash (\) character  (e.g. -
  667.                    ic:\src\include\).  See section 4.4.1 for #include 
  668.                    details.
  669.  
  670.         N<defname>=<defvalue> - specify #define  name and value.  Used to 
  671.                    set debugging switches or constant values without 
  672.                    editing the file.  This option is equivalent to
  673.  
  674.                         #define defname defvalue
  675.  
  676.                    at the begining of the program.
  677.  
  678.         PCC -- The Personal C Compiler                      Page 14
  679.  
  680.  
  681.                    To set <defname> to one, enter n<defname>, which is 
  682.                    equivalent to
  683.  
  684.                         #define defname 1
  685.  
  686.                    Spaces are not allowed.
  687.  
  688.         O<filename> - output filename.  The compiler will produce an 
  689.                    object file with the specified name.  If the name 
  690.                    lacks an extension, the extension '.O' will be added.  
  691.                    The default object name is the same as the source name 
  692.                    with the extension of '.O'.
  693.  
  694.         T<drive>   - specifies the drive that the compiler should use for 
  695.                    its temporary files.  If not specified, the compiler 
  696.                    will build its temporary files on the default drive.  
  697.                    If this drive is close to being full, the 'T' option 
  698.                    should be used to change the drive for the 
  699.                    temporaries.  Also, if the RAM Disk has been 
  700.                    installed, placing the temporary files there will 
  701.                    drastically cut the amount of time needed to compile a 
  702.                    program.
  703.  
  704.  
  705.         4.2. Examples
  706.  
  707.         PCC blip
  708.                    compiles the file named blip.c.  The object file will 
  709.                    be named blip.o.
  710.  
  711.         m:PCC b:blip.ccc tm dm
  712.  
  713.                    runs the compiler from drive M on the file b:blip.ccc.  
  714.                    Temporary files are also written on drive M.  Note the 
  715.                    use of the D option to indicate the location of the 
  716.                    other passes of the compiler.  The object file will 
  717.                    also be named blip.o.
  718.  
  719.         PCC blip -ic:\inc\ -a -nNewVersion -nNYear=1985
  720.  
  721.                    compiles the file named blip.c.  Include files are 
  722.                    taken from the directory c:\inc\.  An assembly 
  723.                    language file is generated named blip.a.  The 'N' 
  724.                    options are equivalent to adding
  725.  
  726.                         #define NewVersion 1
  727.                         #define NYear       1985
  728.  
  729.                    to the start of blip.c
  730.  
  731.         PCC -- The Personal C Compiler                      Page 15
  732.  
  733.  
  734.         4.3. The C Language
  735.  
  736.         PCC compiles C programs that conform to the standard definition 
  737.         of the C language as described in the book The C Programming 
  738.         Language  by Brian W. Kernighan and Dennis M. Ritchie.  The 
  739.         following documentation describes the implementation.
  740.  
  741.         4.3.1. Preprocessor directives
  742.  
  743.         #define    defines a macro with or without parameters. 
  744.  
  745.         #undef, #ifdef and #ifndef - tests the status of the #defined 
  746.                    macros 
  747.  
  748.         #include   includes other files into the program. #include's 
  749.                    can be nested to a maximum depth of 3.
  750.  
  751.                    #include "filename" will search the default directory 
  752.                    for the file filename.  #include <filename> will first 
  753.                    search the default directory for filename.  If the 
  754.                    file was not found, the environment (see DOS 2.X/3.X 
  755.                    SET command) is searched for the variable INCLUDE .  
  756.                    If the variable is found, it is assumed to contain a 
  757.                    set of directory prefixes separated by semi-colons.  
  758.                    For example, if INCLUDE is set as follows
  759.                 
  760.                         C>set include=c:\;c:\usr\include\
  761.  
  762.                    then the line
  763.  
  764.                         #include <world.h>
  765.  
  766.                    would cause PCC to search for
  767.  
  768.                         world.h
  769.                         c:\world.h
  770.                         c:\usr\include\world.h
  771.  
  772.         #if, #else, #endif - conditionally includes or excludes source 
  773.                    statements.
  774.  
  775.         4.3.2. Data Types
  776.  
  777.         char       Unsigned byte with a range of 0 to 255.
  778.  
  779.         int
  780.         short      Signed Integer with a range of -32768 to 32767.
  781.  
  782.         unsigned   Unsigned integer with a range of 0 to 65535.
  783.  
  784.         long       Signed integer with a range of -2147483648 to 
  785.                    2147483647.
  786.  
  787.         float      Four byte floating point value.  A float number has 
  788.                    about 7 digits of precision and has a range of about 
  789.  
  790.         PCC -- The Personal C Compiler                      Page 16
  791.  
  792.  
  793.                    1.E-36 to 1.E+36. The floating point formats are 
  794.                    defined by the IEEE floating-point standard.
  795.  
  796.         double     Eight byte floating point value.  A double number has 
  797.                    about 13 digits of precision and a range of about 1.E-
  798.                    303 to 1.E+303.
  799.  
  800.         (pointer)  pointers are two bytes, limiting total data space to 
  801.                    64KB.
  802.  
  803.         To take advantage of the 8088/8086 instruction set, expressions 
  804.         involving only char  types are not coerced to int before 
  805.         evaluation.  The sum of a char equal to 255 and a char equal to 1 
  806.         is 0 rather than 256.  Constants are considered to be int values 
  807.         so that constant plus char is a two byte integer operation.
  808.  
  809.         4.4. Extensions
  810.  
  811.         The UNIX Version 7 extensions -- enumerated types, extended 
  812.         member name-space, and structure assignment are fully supported.
  813.  
  814.         Enumerated types provide a convenient method of declaring an 
  815.         ordered set of named constants.  Values start with zero, and may 
  816.         be reassigned with a name = value expression.  The same value may 
  817.         be assigned to several names.  For example
  818.  
  819.                 enum color {red, blue=4, green} ca, *cp;
  820.                 enum color cb;
  821.                 if(ca == red)
  822.                         cb = green;
  823.         is equivalent to
  824.  
  825.                 #define red   0
  826.                 #define blue  4
  827.                 #define green 5
  828.                 int ca, *cp;
  829.                 int cb;
  830.                 if(ca == red)
  831.                         cb = green;
  832.  
  833.  
  834.         Extended member name-space relaxes the K&R requirement that if a 
  835.         member name appeared in more than one structure or union, then it 
  836.         had to have the same data type and offset in every appearance.  
  837.         Now, the only restriction is that the member name must be unique 
  838.         within the structure or union.  If a member name is used that is 
  839.         not in the referenced structure, the warning
  840.  
  841.                 member not in structure
  842.  
  843.         is issued.  As a loophole, a pointer to char may be used as an 
  844.  
  845.         PCC -- The Personal C Compiler                      Page 17
  846.  
  847.  
  848.         anonymous pointer to any structure.
  849.                 struct {int i, j, k;} zip;
  850.                 struct {int j; char i;} zap, *zp;
  851.                 char *cp;
  852.  
  853.                 zip.i = 1;      /* OK */
  854.                 zap.i = 1;      /* OK */
  855.                 zap.k = 1;      /* WARNING */
  856.                 zp->i = 1;      /* OK */
  857.                 zp->k = 1;      /* WARNING */
  858.                 cp->k = 1;      /* OK, ANONYMOUS */
  859.  
  860.         Structures can be assigned, used as parameters, or returned from 
  861.         a function.  CAUTION: this may create problems with existing 
  862.         programs because previous versions of PCC converted the name of a 
  863.         structure in a parameter list to a pointer to that structure, 
  864.         while the current release pushes the entire structure.  To 
  865.         highlight this potential problem, PCC will issue the following 
  866.         warning
  867.  
  868.                 structure assignment
  869.  
  870.         when structures are passed by value, and the warning
  871.  
  872.                 returns structure
  873.  
  874.         when a function returns a structure.  These warnings will be 
  875.         removed in a future release.
  876.                 
  877.                 struct z {int i, j;} zip, zap, zxax();
  878.                 main(){
  879.                         zip = zap;  /* structure assignment */
  880.                         zap = zmax(zip, zap);
  881.                         }
  882.                 struct z zmax(a,b) /* func returns struct */
  883.                         struct z a, b; {
  884.                         if(a.i > b.i)
  885.                                 return a;
  886.                         return b;
  887.                         }
  888.  
  889.         Variable names are significant to 31 characters instead of 8.
  890.  
  891.         A #asm directive has been included to allow in-line assembly 
  892.         language code for time critical applications.  All lines 
  893.         following a line starting with #asm are  passed through to the 
  894.         assembler.  The next line beginning with the "#' character, ends 
  895.         the in-line assembly code.
  896.  
  897.         PCC -- The Personal C Compiler                      Page 18
  898.  
  899.  
  900.         For example:
  901.  
  902.                 _move(count, src, tar)
  903.                 int count; char *src, *tar; {
  904.                 #asm
  905.                         MOV             CX,[BP+4] ;count
  906.                         MOV             SI,[BP+6] ;src
  907.                         MOV             DI,[BP+8] ;dst
  908.                         MOV             AX,DS
  909.                         MOV             ES,AX
  910.                         CLD
  911.                         REP MOVSB
  912.                 #
  913.                         }
  914.  
  915.         4.4.1. Forward References
  916.  
  917.         PCC is effectively a one pass compiler so forward references will 
  918.         not work.  The following program:
  919.  
  920.               main() {
  921.                   i=99;
  922.                   }
  923.              extern int i;
  924.  
  925.         will produce a warning that 'i' is undefined and is assumed to be  
  926.         a local variable named 'i'.  The global variable 'i' will not be 
  927.         changed.
  928.  
  929.         Structure tags must be defined before being referenced.  The only 
  930.         exception is pointers, so that legal structure declarations 
  931.         include structures of the form:
  932.  
  933.  
  934.             struct a {
  935.                 struct b *x;
  936.                 }
  937.  
  938.             struct b {
  939.                 struct a *y;
  940.                 }
  941.  
  942.  
  943.         4.4.2. Externs
  944.  
  945.         The rules for 'extern' declarations are:
  946.  
  947.         1.   Statements that are global to the source file, like 'int 
  948.              blip;' may be in several different files that are linked 
  949.              together.  PCCL will allocate 2 bytes for the global 
  950.              integer variable blip.  This is an extension to the standard 
  951.              rule that restrict global declarations to a single file and 
  952.              require all the other declarations to be extern.
  953.  
  954.         PCC -- The Personal C Compiler                      Page 19
  955.  
  956.  
  957.         2.   A declaration that includes the keyword 'extern' may not 
  958.              include initializers and does not allocate any memory.  Thus 
  959.              a variable so declared must be declared somewhere else 
  960.              without the 'extern' keyword in order to reserve memory for 
  961.              the variable.  For example, if a file contains the 
  962.              declaration extern int blip   then some other file must 
  963.              contain the declaration   int blip to actually allocate 
  964.              storage.  If this is not done, the binder will complain 
  965.              about a reference to the unresolved symbol blip.  It is 
  966.              permissible to have both an 'extern' and non-'extern' 
  967.              declaration in a single file.  For example,
  968.  
  969.  
  970.                 extern int blip;
  971.                 int blip;
  972.  
  973.              is valid.
  974.  
  975.         To create include files containing data declarations -- if the 
  976.         variable is not initialized (which means it will be initialized 
  977.         with zeros) either include the declaration:
  978.  
  979.                 int blip;
  980.  
  981.         in every file or include the declaration:
  982.  
  983.                 extern int blip;
  984.  
  985.         in every file and add the declaration:
  986.  
  987.                 int blip;
  988.  
  989.         to one of the files to actually allocate the storage.
  990.  
  991.         If the variable needs initialization, the second approach must be 
  992.         used.  Include the declaration:
  993.  
  994.                 extern int blip;
  995.  
  996.         in the include file.  Initialize the value in only one file:
  997.  
  998.                 int blip = 1985;
  999.  
  1000.         These rules are about the same as Version 7 UNIX.  Extern rules 
  1001.         are an area of C that are currently controversial.  System V UNIX 
  1002.         tried to tighten up the rules but enough people complained that 
  1003.         5.2 is back to normal.
  1004.  
  1005.         PCC -- The Personal C Compiler                      Page 20
  1006.  
  1007.  
  1008.         4.4.3. Macros
  1009.  
  1010.         Macro arguments are not replaced within a quoted string.   For 
  1011.         example, in The C Puzzle Book by Alan Feuer the macros in 
  1012.         <defs.h> use the following construct to customize printf() calls.
  1013.  
  1014.                 #define PR(fmt,v)printf("value=%fmt%t",v);
  1015.  
  1016.         This does not work with the PCC compiler.  Instead add the 
  1017.         following defines to <defs.h>:
  1018.  
  1019.                 #define D "value = %d%t"
  1020.                 #define F "value = %f%t"
  1021.                 #define C "value = %c%t"
  1022.                 #define G "value = %g%t"
  1023.  
  1024.         and change the PR define to
  1025.  
  1026.                 #define PR(fmt,v)printf(fmt,(v));
  1027.  
  1028.         Statements of the type
  1029.  
  1030.             PRINT1(d,x);
  1031.  
  1032.         must be changed to
  1033.  
  1034.             PRINT1(D,x);
  1035.  
  1036.         in the programs.  Lower case D, F, C, and G's would allow the 
  1037.         programs to remain unchanged but variables c and g are used in 
  1038.         structure one and variable g is used in structures two and three.
  1039.  
  1040.  
  1041.         4.4.4. Strings
  1042.  
  1043.         Literal character strings delimited by quotes ('\"') cannot 
  1044.         contain the NUL character ('\0').  The compiler terminates the 
  1045.         string at the NUL character, even though it checks that the 
  1046.         string has a terminating quote character.  If you want NUL 
  1047.         characters in the string for initialization purposes, use an 
  1048.         array assignment.
  1049.  
  1050.                 char init1[]="abcdef@xyz@012", *ip=init1;
  1051.                 
  1052.                 while(ip = index(ip, '@'))
  1053.                         *ip = '\0';
  1054.  
  1055.         The PCCA 8088 Assembler                            Page 21
  1056.  
  1057.  
  1058.         5. The PCCA 8088 Assembler
  1059.  
  1060.         5.1. Introduction
  1061.  
  1062.         PCCA is the 8088/8086 assembler.  It reads assembly language 
  1063.         source files and produces linkable object files.
  1064.  
  1065.         5.2. Invocation
  1066.  
  1067.             PCCA <filename> [ options ]
  1068.  
  1069.         <filename> is the name of the assembly language source file.  If 
  1070.                    it does not include an extension Q the extension '.A' 
  1071.                    is assumed.
  1072.  
  1073.         Options: The case of the option is not significant. Each option 
  1074.         should be separated from other options by blanks.  Options may be 
  1075.         preceded with the dash (-) character.
  1076.  
  1077.         L[ <filename> ] -- The assembler will produce a listing from the 
  1078.                    assembly language input.  This listing includes the 
  1079.                    hex-values generated by the assembler as well as line 
  1080.                    numbers and pagination.  If no name is specified, then 
  1081.                    the name of the source file with the extension '.L' is 
  1082.                    used.  If the specified file does not have an 
  1083.                    extension, '.L' will be used.  Otherwise the listing 
  1084.                    is written to the specified file.  To generate a 
  1085.                    listing on the printer, use '-LPRN:'.
  1086.  
  1087.         O<filename> The assembler will produce an object file with the 
  1088.                    specified name.  If the name lacks an extension, then 
  1089.                    the extension '.O' will be appended to the name.  The 
  1090.                    default object file name is the name of the source 
  1091.                    file with the extension changed to '.O'.
  1092.  
  1093.         T<drive>   The 'T' option specifies the drive where the assembler 
  1094.                    temporary files will be created.  If a RAM Disk is 
  1095.                    available, redirecting temporary files to that drive 
  1096.                    will greatly speed development.  The assembler 
  1097.                    normally creates its temporary files on the default 
  1098.                    drive/directory.
  1099.  
  1100.         Pnn        Specifies page length, in lines.  The default is 66.
  1101.  
  1102.         Wnn        Specifies page width, in characters, for the list 
  1103.                    file. The value nn must be a number from 60 to 132.  
  1104.                    The default is 80.
  1105.  
  1106.         5.3. Example
  1107.  
  1108.  
  1109.         PCCA blip
  1110.                    assembles the file named blip.a and produces an object 
  1111.                    file named blip.o.
  1112.  
  1113.         The PCCA 8088 Assembler                            Page 22
  1114.  
  1115.  
  1116.         M:PCCA blip.asm -Ob:blip Lblip.lst
  1117.  
  1118.                    runs the assembler from drive M: on the file named 
  1119.                    blip.asm.  The output is an object file named blip.o 
  1120.                    on drive B: and a listing file named blip.lst on the 
  1121.                    default drive.
  1122.  
  1123.         PCCA blip.a TM -oa:blip.o -lb:blip.lst
  1124.  
  1125.                    assembles the file named blip.a.  Temporary files are 
  1126.                    created on drive M:.  The output of the assembler is 
  1127.                    placed on drive A: in the file blip.o.  A listing file 
  1128.                    is generated and written to drive B: in the file 
  1129.                    blip.lst
  1130.  
  1131.         The PCCL Object File Linker                        Page 23
  1132.  
  1133.  
  1134.         6. The PCCL Object File Linker
  1135.  
  1136.         6.1. Introduction
  1137.  
  1138.         PCCL is the program that links together object and library  
  1139.         modules and forms an executable program.  For very long command 
  1140.         lines, see the -f option.
  1141.  
  1142.  
  1143.         6.2. Invocation
  1144.  
  1145.                 PCCL <filename> <filename> ...  [options]
  1146.  
  1147.         <filename> A sequence of filenames separated by blanks. The 
  1148.                    filenames should be the names of object (.O) or 
  1149.                    library (.S) files.  If a filename does not have an 
  1150.                    extension, '.O' is assumed.  PCCL automatically looks 
  1151.                    for the supplied library PCCS.S so its name should 
  1152.                    not be included in the list of filenames.
  1153.  
  1154.         Options: All options may be in upper or lower case.  Options must 
  1155.         be separated by  blanks and preceded by a hyphen to differentiate 
  1156.         them from <filename>s.  Note that this is different from other 
  1157.         commands where the hyphen is optional.
  1158.  
  1159.         -A         The assembler option keeps PCCL from generating the C 
  1160.                    initialization code.  Instead, execution begins at the 
  1161.                    beginning of the code rather than starting at the 
  1162.                    main_ public label.  ARGC and ARGV are not calculated 
  1163.                    and the stack is not set up.  Uninitialized variables 
  1164.                    are not filled with zero.  Library functions such as 
  1165.                    creat() and open() cannot be used as they depend on 
  1166.                    the zero initialization.  The 'A' and 'S' options are 
  1167.                    useful for a few cases but caution should be exercised 
  1168.                    in their use.
  1169.  
  1170.         -F<filename> identifies a file containing <filename>s and options 
  1171.                    to be used by PCCL.  This is used for very long lists 
  1172.                    of filenames and options.
  1173.  
  1174.         -L<name>   specifies the drive/directory containing the PCCS.S 
  1175.                    standard library.  If this option is not specified, 
  1176.                    the PCCS.S file must be on the default drive.  With 
  1177.                    MS-DOS 2.0 and later versions of the operating system,  
  1178.                    the PATH system parameter is used to locate the 
  1179.                    library.
  1180.  
  1181.         -Mn        Indicates that the object files following this control 
  1182.                    should be collected in the memory-based overlay 
  1183.                    indicated by the value n ( 1 to 39 ).  See the 
  1184.                    description on overlays below for details on the 
  1185.                    overlay mechanism.
  1186.  
  1187.         -O<filename> changes the name of the output file to 
  1188.                    <filename>.EXE.  If this option is not specified, the 
  1189.  
  1190.         The PCCL Object File Linker                        Page 24
  1191.  
  1192.  
  1193.                    name of the first object file in the list with the 
  1194.                    .EXE extension will be used.
  1195.  
  1196.         -P[<filename>] Generates a sorted list of publics and offsets.  C 
  1197.                    procedures and data declared outside of procedures are  
  1198.                    automatically public (or extern)  unless explicitly 
  1199.                    declared static.  Publics with names starting with an 
  1200.                    underline '_' are not listed unless the -_ option is 
  1201.                    also specified. The optional name is the destination 
  1202.                    for the publics list.  If omitted, the publics and 
  1203.                    offsets are listed on the console.  The size of 
  1204.                    overlays, if any, will also be displayed.
  1205.  
  1206.         -Shhhh     specifies the stack size.  hhhh is in hex.   Normally, 
  1207.                    PCCL will set the stack size as large as possible.  
  1208.                    The '-S' option can be used to limit this size for use 
  1209.                    with exec().
  1210.          
  1211.         -Vn        This option is used to create disk-based overlays.  
  1212.                    All object files following this option, until the end 
  1213.                    of the list or another overlay option, are collected 
  1214.                    into the overlay indicated by the value n (1 to 39).  
  1215.                    See the overlay section below for details.
  1216.  
  1217.         -_ (underscore) PCCL normally suppresses names that start with an 
  1218.                    underscore (usually internal names) from the publics 
  1219.                    list. The underscore option restores these publics to 
  1220.                    the listing.  This option is useful when you need to 
  1221.                    see all the modules bound to your program.
  1222.  
  1223.  
  1224.         6.3. Examples
  1225.  
  1226.  
  1227.  
  1228.         PCCL blip
  1229.                    binds the file blip.o with PCCS.S and produces the 
  1230.                    executable file blip.exe.
  1231.  
  1232.         PCCL proga progb progc lib.s -p
  1233.  
  1234.                    binds the files proga.o, progb.o, and progc.o with the 
  1235.                    user library lib.s  and the standard I/O library, 
  1236.                    PCCS.S, into the application file proga.exe.  The 
  1237.                    map is printed on the screen.
  1238.  
  1239.         PCCL proga progb -V1 progc -V2 progd -Pmap -_ -Omyprog
  1240.  
  1241.                    binds the files proga.o, progb.o with PCCS.S and 
  1242.                    creates the executable file myprog.exe and the overlay 
  1243.                    file myprog.ov which contains two overlays consisting 
  1244.                    of the object files progc.o and prod.o.  The publics 
  1245.                    map is sent to the file named map and will also list 
  1246.                    the internal names that begin with the underline ('_') 
  1247.                    character.
  1248.  
  1249.         The PCCL Object File Linker                        Page 25
  1250.  
  1251.  
  1252.         6.4. Space Considerations
  1253.  
  1254.         A program is restricted to a maximum of 64KB of code and 64KB of 
  1255.         data plus the stack.  PCCL calculates the size of code and data 
  1256.         and will report the size of each segment (in hex) when the -P 
  1257.         option is specified.  PCCL cannot calculate the actual stack 
  1258.         requirements.  If the 'stack' and 'locals' size reported by PCCL 
  1259.         seems small, the actual stack requirements should be calculated 
  1260.         by hand to make sure there is enough space.  The actual 
  1261.         requirements are the worst case of four bytes per call plus the 
  1262.         size of locals (including parameters) for all active procedures 
  1263.         plus about 500 bytes for the Operating System calls.  In 
  1264.         practice, 2KB plus the size of the local arrays simultaneously 
  1265.         active should be sufficient.
  1266.  
  1267.         If PCCL reports that the code limit is exceeded, look in the 
  1268.         publics map for the scanf() and printf() routines.  These are 
  1269.         relatively large routines (around 2KB each) and also link in the 
  1270.         floating-point routines.  Eliminating the use of these routines 
  1271.         can result in a large savings.  If scanf() and/or printf() are 
  1272.         necessary but no floating-point values will be used, try using 
  1273.         the PCC7.S instead of the standard PCCS.S library (Rename 
  1274.         the PCCS.S library to something else and rename the PCC7.S 
  1275.         library to PCCS.S).  This will assume the availability of the 
  1276.         8087 math chip and will not bring in the software floating-point 
  1277.         routines.
  1278.  
  1279.  
  1280.         6.5. Overlays
  1281.  
  1282.         Another way to solve the space problem is the use of overlays.  
  1283.         The overlay system provided by this package is very simple.  An 
  1284.         application is divided into a root portion that is always 
  1285.         resident and two or more overlays.  Only one overlay is resident 
  1286.         (executable) at any given time.  The following diagram outlines 
  1287.         the relationship between the root and the overlays:
  1288.  
  1289.  
  1290.         There are two types of overlays, disk-based overlays and memory-
  1291.         based overlays.  The difference between the two types is the 
  1292.         location of the overlays.  Disk-based overlays, created with the 
  1293.         -V option, are stored in a separate file.  Memory-based overlays, 
  1294.         created with the -M option, are loaded into memory along with the 
  1295.         root code.  Memory-based overlays should only be used when there 
  1296.         is sufficient memory for the root and all of the overlays.  The 
  1297.         advantage of memory-based overlays over disk-based overlays is in 
  1298.         the amount of time needed to make an overlay resident, memory-
  1299.         based overlays being much faster to load.
  1300.  
  1301.         The application program is responsible for initializing the 
  1302.         overlay subsystem and ensuring that the correct overlay is 
  1303.         resident before calling any of the functions in the overlay.
  1304.  
  1305.         For disk-based overlays, the routine overlay_init() must be 
  1306.         called from the root with the name of the overlay file to 
  1307.  
  1308.         The PCCL Object File Linker                        Page 26
  1309.  
  1310.  
  1311.         initialize the overlay system.  Overlays are loaded by calling 
  1312.         the routine overlay(n) where n is the number of the overlay to be 
  1313.         made resident.
  1314.  
  1315.         For memory-based overlays instead of disk-based overlays, do not 
  1316.         call the overlay_init() routine and call the routine moverlay() 
  1317.         in place of the routine overlay().
  1318.  
  1319.         In the following example the root is composed of the file X.C.  
  1320.         The first overlay is the file Y.C and the second overlay is in 
  1321.         the file Z.C.
  1322.  
  1323.  
  1324.         File X.C:
  1325.                 main() {
  1326.                         overlay_init("X.OV"); /* initialize */
  1327.                         puts("this is the root program\n");
  1328.                         overlay(1); /* make 1st overlay resident */
  1329.                         zip();    /* call into 1st overlay */
  1330.                         overlay(2); /* make the second resident */
  1331.                         zap();    /* call into second overlay */
  1332.                         puts("bye\n");
  1333.                         }
  1334.  
  1335.         File Y.C:
  1336.                 zip() {
  1337.                         puts("  this is ZIP  ");
  1338.                         }
  1339.  
  1340.         File Z.C:
  1341.                 zap() {
  1342.                         puts("  this is ZAP  ");
  1343.                         }
  1344.  
  1345.  
  1346.         The files are compiled in the usual fashion:
  1347.  
  1348.                 PCC x
  1349.                 PCC y
  1350.                 PCC z
  1351.  
  1352.         Ordinarily, the files would be linked together using the command:
  1353.  
  1354.                 PCCL x y z
  1355.  
  1356.         Instead, to create the two overlays, the command:
  1357.  
  1358.                 PCCL x -V1 y -V2 z
  1359.          
  1360.         is used.  The -V option is followed by the overlay number.  This 
  1361.         number starts at 1 and runs in ascending order up to 39.  All 
  1362.         files following the -V or the -M option are included in the 
  1363.         overlay.  All library modules (from .S files) are included in the 
  1364.         root.  The result from the execution of the PCCL program with the 
  1365.         -V option is the executable root (.EXE) file and the overlay 
  1366.  
  1367.         The PCCL Object File Linker                        Page 27
  1368.  
  1369.  
  1370.         (.OV) file which contains the overlays.  The result with the -M 
  1371.         option is an .EXE file containing both the root and the overlays.
  1372.  
  1373.         The -P option of PCCL will also display the size of each overlay 
  1374.         as well as the overlay for each symbol.
  1375.  
  1376.  
  1377.         6.6. Libraries
  1378.  
  1379.         Libraries are just concatenated .O files. The .S extension tells 
  1380.         PCCL to only include modules that are referenced. If all of the 
  1381.         routines in a library are required, rename the .S file to a .O 
  1382.         file to force all of the modules in the library to be included.
  1383.  
  1384.         PCCL includes the entire .O module  from a library if any of its 
  1385.         public names have been selected by other object modules processed 
  1386.         by PCCL.  Thus, if a .O file contains several functions, all of 
  1387.         them will be bound into a program if any of them are called.
  1388.  
  1389.         PCCL searches a library once.  Thus if you have two modules, A 
  1390.         and B, and A calls B , the B must follow A in the library.  LIB88 
  1391.         attempts to order the library so that these inter-library 
  1392.         references are ordered so that PCCL will find them.  One way 
  1393.         around any circular dependencies (e.g., B  also calls A ) is to 
  1394.         include the library twice on the command line.
  1395.  
  1396.         The PCCS.S Standard Library                       Page 28
  1397.  
  1398.  
  1399.         7. The PCCS.S Standard Library
  1400.  
  1401.         7.1. Introduction
  1402.  
  1403.         This section describes the standard library, PCCS.S, for the 
  1404.         PCC C compiler and PCCA assembler.  This library includes 
  1405.         routines similar to routines available in UNIX with some 
  1406.         inevitable differences due to the MS-DOS Operating System.  
  1407.  
  1408.         All of the routines are in the PCCS.S library file provided on 
  1409.         the distribution disk.  This file must be on the default 
  1410.         drive/directory, in a directory listed in the PATH system 
  1411.         parameter,  or on the drive/directory referred to by the '-L' 
  1412.         option for PCCL to execute correctly.
  1413.  
  1414.         There is a PCC7.S library that has the same functions as the 
  1415.         PCCS.S libarary but assumes the availability of the 8087 math 
  1416.         chip to perform the floating-point operations.  To use the 8087, 
  1417.         rename PCC7.S to PCCS.S.
  1418.  
  1419.         7.2. Names
  1420.  
  1421.         Public names starting with the underline character ('_') are  
  1422.         reserved for PCC internal routines and should be avoided.  Names 
  1423.         of this form are also employed for user callable routines such as 
  1424.         _move() whose names might conflict with user names.
  1425.  
  1426.         PCC automatically appends the underline character ('_') to the 
  1427.         end of public names to avoid conflicts with assembly language 
  1428.         reserved words.  PCCA does not do this so the underline must be 
  1429.         manually appended to publics used to link with code generated by 
  1430.         PCC.  For example, the C puts() routine should be referred to as 
  1431.         puts_ from assembler.   PCCL ignores the case of publics, unlike 
  1432.         UNIX, so  puts_ matches the name PutS_.
  1433.  
  1434.         7.3. Program Initialization
  1435.  
  1436.         PCCL inserts a jmp _csetup as the first executable instruction in 
  1437.         the program.  _CSETUP performs the following initialization 
  1438.         functions:
  1439.  
  1440.         1. sets the data/stack segment size to the lower of: available 
  1441.            memory, 64K, or the size of the static data area plus the PCCL 
  1442.            -S option,
  1443.         2. Formats argc and argv[] from the Program Segment Prefix,
  1444.         3. Zeros the Uninitialized Data Area, and
  1445.         4. Calls main(argc, argv)
  1446.  
  1447.         Assembly language main programs that require normal 
  1448.         initialization should contain the following
  1449.  
  1450.                 PUBLIC MAIN_
  1451.                 MAIN_:
  1452.  
  1453.         The PCCS.S Standard Library                       Page 29
  1454.  
  1455.  
  1456.         The initialization code will set the SS, DS and SP registers so 
  1457.         that there is the largest possible stack unless the PCCL '-S' 
  1458.         option is used to restrict the stack size.  The stack grows 
  1459.         towards the unitialized data area.  The figure below shows the 
  1460.         memory layout after the initialization code has run:
  1461.  
  1462.              +-------------------+
  1463.              |     Stack         |
  1464.              +-------------------+<- SP,BP
  1465.              |                   |
  1466.              /     Heap          /
  1467.              +-------------------+<- _memory()
  1468.              |    Un-Init Data   |
  1469.              +-------------------+
  1470.              |    Init Data      |
  1471.              +-------------------+<- DS,SS
  1472.              |    Code           |
  1473.              +-------------------+<- CS
  1474.              |    PSP            |
  1475.              +-------------------+
  1476.  
  1477.         Fig. 7-1: Initial Memory Layout
  1478.  
  1479.         The memory between the end of the uninitialized area and the 
  1480.         stack is not normally used by PCC or the program (unless the 
  1481.         program needs an inordinate amount of stack).  This area is 
  1482.         considered to be free memory.  This memory area can be accessed 
  1483.         directly by using the _memory() and _showsp() routines to 
  1484.         calculate its extent.  Another way to access this memory is to 
  1485.         use the malloc() routine.  Do not use both methods.  Remember to 
  1486.         leave enough space for the stack to grow.
  1487.  
  1488.         The -A option of PCCL inhibits the call to _csetup.  Execution 
  1489.         commences with the first instruction of the first filename 
  1490.         specified to PCCL.  On entry, the registers have the following 
  1491.         values:
  1492.  
  1493.         CS      Address of Code Segment.  Execution starts at CS:0.
  1494.         SS      Address of Data Segment.
  1495.         ES,DS   Address of Program Segment Prefix
  1496.         SP      Stack size set by PCCL
  1497.  
  1498.         The source code for _csetup is in the file ISETUP.A. 
  1499.  
  1500.         7.4. Calling Conventions
  1501.  
  1502.         Arguments to a function are pushed on the stack, rightmost 
  1503.         argument first.  It is the responsibility of the calling function 
  1504.         to clean up the stack.  For example
  1505.  
  1506.                 int i;
  1507.  
  1508.                 zip(i, 6);
  1509.  
  1510.         The PCCS.S Standard Library                       Page 30
  1511.  
  1512.  
  1513.         would generate the following code
  1514.  
  1515.                 mov     ax,6
  1516.                 push    ax
  1517.                 push    word i_
  1518.                 public zip_
  1519.                 call    zip_
  1520.                 add     sp,4
  1521.  
  1522.         The word modifier is required because PCC allocates two bytes for 
  1523.         ints.  The add sp,4 removes the two words that were pushed as 
  1524.         parameters to zip_.  Note the PCC appended '_' on names.  If 
  1525.         there had been no local variables defined in the function, the 
  1526.         clean-up code would have been
  1527.  
  1528.                 mov     sp,bp
  1529.  
  1530.         which is faster.
  1531.  
  1532.         Data is pushed on the stack as follows:
  1533.  
  1534.                 
  1535.         char       pushed as a word, with high-order byte set to zero
  1536.  
  1537.                         mov  AL,data_
  1538.                         mov  AH,0
  1539.                         push AX
  1540.  
  1541.         int        pushed as a word
  1542.         unsigned
  1543.                         push WORD data_
  1544.  
  1545.         long       pushed with least-significant word pushed last
  1546.  
  1547.                         push WORD data_[2]
  1548.                         push WORD data_[0]
  1549.  
  1550.         float      Changed  to  double and pushed with  least-significant 
  1551.                    word pushed last
  1552.  
  1553.                         mov  si,offset data_
  1554.                         PUBLIC _FLOADE  ; load float
  1555.                         call _FLOADE
  1556.                         PUBLIC _FPUSH   ; push double
  1557.                         call _FPUSH
  1558.  
  1559.         double     pushed with least-significant word pushed last
  1560.  
  1561.                         push WORD data_[6]
  1562.                         push WORD data_[4]
  1563.                         push WORD data_[2]
  1564.                         push WORD data_[0]
  1565.  
  1566.         The PCCS.S Standard Library                       Page 31
  1567.  
  1568.  
  1569.         struct     push  (sizeof(struct)  + 1) >> 1  words,  with  least-
  1570.                    significant word pushed last.
  1571.  
  1572.                         mov  cx,nn    ; size in words
  1573.                         sub  sp,cx    ; make room on stack
  1574.                         mov  di,sp    ; target
  1575.                         mov  si,offset data_  ; source
  1576.                         mov  ax,ds    ; setup
  1577.                         mov  es,ax    ;    es
  1578.                         cld           ; set direction up
  1579.                 rep     movsw         ; copy to stack
  1580.  
  1581.  
  1582.         7.5. LIBRARY CONVENTIONS
  1583.  
  1584.         Called functions are responsible for preserving CS, DS, SS, SP, 
  1585.         and BP across the function call.  All other registers need not be 
  1586.         maintained.  The usual preamble for a called function is
  1587.  
  1588.                         PUBLIC fname_
  1589.                 fname_:
  1590.                         push bp      ; save old frame pointer
  1591.                         mov  bp,sp   ; establish local frame
  1592.  
  1593.         For functions that don't return structures, parameters begin in 
  1594.         the local frame at [bp+4], and continue upward based on the size 
  1595.         of each parameter.  Thus  for the fragment
  1596.  
  1597.                 blip(x, y, z)
  1598.                 int x;
  1599.                 long y;
  1600.                 double z;
  1601.  
  1602.         the parameters would be referenced in Assembler as
  1603.  
  1604.                 mov  cx,WORD [bp+4]  ; x_
  1605.                 mov     ax,WORD [bp+6]  ; lsw of y_
  1606.                 mov  dx,WORD [bp+8]  ; msw of y_
  1607.                 lea  si,[bp+10]      ; addr of z_
  1608.  
  1609.         For functions that do return structures, [bp+4] contains a 
  1610.         pointer to where the structure should be returned.  So if the 
  1611.         above fragment was
  1612.  
  1613.                 struct foo blip(x, y, z)
  1614.  
  1615.         the parameters would be
  1616.  
  1617.                 mov  cx,WORD [bp+06]  ; x_
  1618.                 mov     ax,WORD [bp+08]  ; lsw of y_
  1619.                 mov  dx,WORD [bp+10]  ; msw of y_
  1620.                 lea  si,[bp+12]       ; addr of z_
  1621.  
  1622.         The PCCS.S Standard Library                       Page 32
  1623.  
  1624.  
  1625.         Local variables are allocated below the current frame pointer, 
  1626.         regardless of what the function returns, so that the fragment
  1627.  
  1628.                 {
  1629.                 int aa[2];
  1630.                 long b;
  1631.  
  1632.         would be referenced as
  1633.  
  1634.                 sub  sp,8       ; allocate space for locals
  1635.                 mov  ax,[bp-4]  ; aa_[1]
  1636.                 mov     dx,[bp-8]  ; msw b_
  1637.  
  1638.         The standard exit sequence is
  1639.  
  1640.                 mov     sp,bp   ; reclaim any local space
  1641.                 pop     bp      ; old frame pointer
  1642.                 ret          ; caller will clean up stack
  1643.  
  1644.         Values  are  returned from functions as followings:
  1645.  
  1646.              char      returned  in AX.   char values are returned in  AL 
  1647.                        with AH
  1648.              int       set to zero
  1649.              unsigned
  1650.  
  1651.              long      returned in DX:AX.  (AX contains lsw)
  1652.  
  1653.              double    returned on floating point stack (s/w or 8087). 
  1654.              float
  1655.  
  1656.              struct    returned to address in [bp+4]
  1657.  
  1658.         7.6. Disk Input/Output Routines
  1659.  
  1660.         In this implementation of C I/O, procedures like getc() are 
  1661.         functions rather than macros and a file identifier FILE is simply  
  1662.         an integer containing the file number rather than a pointer to a 
  1663.         structure.  This change means that read() and getc() calls may be 
  1664.         intermingled and there is little difference between open() and 
  1665.         fopen() on a file.
  1666.  
  1667.         In UNIX there is a distinction between file and stream I/O.  
  1668.         Crudely stated, the functions that have 'f' as their first letter  
  1669.         (fopen(), fread() etc.) deal with streams, and other primitives 
  1670.         (open(),  read() etc.) access files.  These two forms of I/O are 
  1671.         compatible -- fopen() may be used to open a file a file and then 
  1672.         read() used to read it -- but it is best to use either the stream 
  1673.         or file primitives only for a particular file for portability.  
  1674.         The FILE type is defined in the stdio.h include file and is 
  1675.         simply an int type.  This int contains the file number, the same 
  1676.         number returned by open() and creat().  To use the stream 
  1677.         routines with a file opened with the open(), merely pass the file 
  1678.         number. 
  1679.  
  1680.         The PCCS.S Standard Library                       Page 33
  1681.  
  1682.  
  1683.         The stream style of I/O primitives are: fopen() to open a file, 
  1684.         fread(), fgets() or fgetc() [getc()] to read,  fwrite(), fputs() 
  1685.         or fputc() [putc()] to write, fseek() to seek, fflush() to write 
  1686.         out internal buffers, and fclose() to close.
  1687.  
  1688.         The file type I/O primitives are: open(), creat(), read(),  
  1689.         write(), lseek(), and close().
  1690.  
  1691.         The maximum number of files that can be open at one time is 
  1692.         either 20, or the number specified in CONFIG.SYS, whichever is 
  1693.         less. See section 2.3 for details about CONFIG.SYS.  New files 
  1694.         are creat()'d and old files are open()'d.
  1695.  
  1696.         A closed file may be rename()'d or unlink()'d (deleted).
  1697.  
  1698.         Three predefined file numbers may be used to read from or write 
  1699.         to the console.  To use them, include the following defines in 
  1700.         the program:
  1701.  
  1702.           #define stdin   0
  1703.           #define stdout  1
  1704.           #define stderr  2
  1705.  
  1706.  
  1707.         7.7. Math Routines
  1708.  
  1709.         If any of the transcendental or sqrt() functions are used, 
  1710.         include the file math.h or the equivalent declarations to specify 
  1711.         them as returning double's.
  1712.  
  1713.         math.h includes the statement 
  1714.  
  1715.                 extern int errno;
  1716.  
  1717.         errno is set to a non-zero value: on floating point stack errors,  
  1718.         if an argument to a math routine is out of range, or if the 
  1719.         result of a math routine would under/overflow.  Error codes and 
  1720.         names (defined in math.h) are:
  1721.  
  1722.         30 ESTK   F/P stack overflow.  The most probable cause is calling 
  1723.                   a function that returns a double without declaring it 
  1724.                   as such to the compiler.  After eight calls, the f/p 
  1725.                   stack will be full.
  1726.  
  1727.         33 EDOM   invalid argument, i.e., sqrt(-1.0).
  1728.  
  1729.         34 ERANGE invalid arg size, i.e., asin(2.0).
  1730.  
  1731.         The function  rerrno() is called by the floating point routines 
  1732.         whenever an error is detected.  rerrno() prints out an 
  1733.         appropriate error message and calls exit().  In order to bypass 
  1734.         this effect, install the following function in your program
  1735.  
  1736.                 rerrno() {;}  /* null function to suppress printing */
  1737.  
  1738.         The PCCS.S Standard Library                       Page 34
  1739.  
  1740.  
  1741.         7.8. IBM-PC Screen and Keyboard Interface
  1742.  
  1743.         A number of functions have been written to simplify the interface 
  1744.         between C programs and the IBM-PC and its clones.  These routines 
  1745.         are not in the standard PCCS.S library but are distributed in 
  1746.         source form in the file PCIO.A.  To use these routines, they must 
  1747.         be assembled and bound in.  For example:
  1748.  
  1749.                 A>PCCA b:pcio
  1750.                 A>PCCL b:blip b:pcio
  1751.  
  1752.         See the comments in the IBM Technical Reference Manual for 
  1753.         details on the BIOS interface used by PCIO.
  1754.  
  1755.         See the LIB88 chapter for details on installing PCIO.O in 
  1756.         PCCS.S.
  1757.  
  1758.         7.9. Standard Library Functions
  1759.  
  1760.  
  1761.         7.9.1. abs()
  1762.  
  1763.                   unsigned uval;
  1764.                   int y;
  1765.  
  1766.                   uval = abs(y);
  1767.  
  1768.         abs returns |y| (absolute value).
  1769.  
  1770.  
  1771.         7.9.2. atoi()
  1772.  
  1773.                   char *cp;
  1774.                   int ival;
  1775.  
  1776.                   ival = atoi(cp);
  1777.                 
  1778.         atoi converts the char array at cp to its corresponding int 
  1779.         value.  The first unrecognized character terminates the 
  1780.         conversion.
  1781.  
  1782.         WS is either a tab or a space.  A digit is an ASCII character '0' 
  1783.         through '9'.  [] delimit sequences that can occur zero or one 
  1784.         time.  {} delimit sequences that can occur zero or many times.
  1785.  
  1786.                 Valid character Sequences
  1787.  
  1788.                 {WS} [-] {DIGIT}
  1789.          
  1790.  
  1791.         SEE ALSO:scanf()
  1792.  
  1793.         The PCCS.S Standard Library                       Page 35
  1794.  
  1795.  
  1796.         NOTES: To guard against int overflow, or large unsigned values 
  1797.         being stored as negative integers, use atol and check that the 
  1798.         high-order word is the same as the high-order bit of the low-
  1799.         order word.
  1800.  
  1801.                 atoi(str)
  1802.                 char *str; {
  1803.                         long val, atol();
  1804.                         int sign, extn;
  1805.  
  1806.                         extn = (val = atol(str)) >> 16;
  1807.                         sign = val & 0x8000;
  1808.                         if((!sign && extn != 0) || (sign && extn != -1))
  1809.                                 overflowErr();
  1810.                         return val;
  1811.                         }
  1812.  
  1813.  
  1814.         7.9.3. atof()
  1815.  
  1816.                   char *cp;
  1817.                   double dval;
  1818.  
  1819.                   dval = atof(cp);
  1820.                 
  1821.         atof converts the char array at cp to its corresponding double 
  1822.         value.  The first unrecognized character terminates the 
  1823.         conversion.
  1824.  
  1825.         WS is either a tab or a space.  A digit is an ASCII character '0' 
  1826.         through '9'.  E is either an ASCII 'E' or 'e'.  [] delimit 
  1827.         sequences that can occur zero or one time.  {} delimit sequences 
  1828.         that can occur zero or many times.
  1829.  
  1830.                 Valid character Sequences
  1831.  
  1832.                 {WS} [-] {digit} ['.'] [{digit} [E [-] {digit}]]
  1833.          
  1834.         SEE ALSO:scanf()
  1835.  
  1836.  
  1837.         7.9.4. atol()
  1838.  
  1839.                   char *cp;
  1840.                   long lval, atol();
  1841.  
  1842.                   lval = atol(cp);
  1843.                 
  1844.         atol converts the char array at cp to its corresponding long 
  1845.         value.  The first unrecognized character terminates the 
  1846.         conversion.
  1847.  
  1848.         The PCCS.S Standard Library                       Page 36
  1849.  
  1850.  
  1851.         WS is either a tab or a space.  A digit is an ASCII character '0' 
  1852.         through '9'.  [] delimit sequences that can occur zero or one 
  1853.         time.  {} delimit sequences that can occur zero or many times.
  1854.  
  1855.                 Valid character Sequences
  1856.  
  1857.                 {WS} [-] {DIGIT}
  1858.          
  1859.  
  1860.         SEE ALSO:scanf()
  1861.  
  1862.                         }
  1863.  
  1864.  
  1865.         7.9.5. ceil()
  1866.  
  1867.                   #include <math.h>
  1868.  
  1869.                   double dval, x;
  1870.  
  1871.                   dval = ceil(x);
  1872.  
  1873.         ceil returns the smallest integer value not less than x.
  1874.  
  1875.  
  1876.         7.9.6. chain()
  1877.  
  1878.                   char *filename, *commandTail;
  1879.  
  1880.                   chain(filename, commandTail)
  1881.  
  1882.         chain will load and execute an arbitrary program Q filename is 
  1883.         the complete pathname of the program (including the .EXE or .COM 
  1884.         suffix).  commandTail  contains the arguments to the program.  
  1885.  
  1886.         chain functions like exec  except that control is not returned to 
  1887.         the calling program.  chain is in the file EXEC.O, in the 
  1888.         distribution. It should be bound in first to save memory since it 
  1889.         loads the called program immediately behind itself.  For example:
  1890.  
  1891.                 A>PCCL EXEC BLIP -OBLIP
  1892.  
  1893.         NOTE: To invoke a Batch file, or a DOS built-in command, use 
  1894.         COMMAND.COM with the '/c' switch as follows.
  1895.  
  1896.                 chain("\\command.com", "/cxxx");
  1897.  
  1898.         Where xxx is one of the DOS built-in commands ( 'dir', 'copy', 
  1899.         Remember that two backslashes are required to insert a single 
  1900.         backslash in a string.  Invoking COMMAND.COM with no parameters 
  1901.         will start another DOS shell.  To return type
  1902.  
  1903.                 exit
  1904.  
  1905.         The PCCS.S Standard Library                       Page 37
  1906.  
  1907.  
  1908.         7.9.7. close()
  1909.  
  1910.                   int handle, stat;
  1911.  
  1912.                   stat = close(handle);
  1913.  
  1914.         close writes any buffered data for the file fp to that file, and 
  1915.         closes the file. Returns -1 if fp is not open, or if an error 
  1916.         occurred writing the buffered data to that file.
  1917.                 
  1918.  
  1919.         7.9.8. creat()
  1920.  
  1921.                   int handle;
  1922.                   char *name;
  1923.  
  1924.                   handle = creat(name)
  1925.  
  1926.         creat creates the file name  and return an int that is used to 
  1927.         reference it in future file operations, or -1 if the file can't 
  1928.         be opened.  If the file name already exists, it is deleted before 
  1929.         it is opened. 
  1930.  
  1931.         NOTES: creat  opens a file in update mode so that after a file is 
  1932.         written,  a program can seek to the begining of the file and read 
  1933.         it without closing the file and reopening it.
  1934.  
  1935.         Any  of  the  functions can open the console ("CON")  or  printer 
  1936.         ("PRN").
  1937.  
  1938.  
  1939.         7.9.9. dates()
  1940.  
  1941.                   char *buf;
  1942.                 
  1943.                   dates(buf);
  1944.  
  1945.         dates formats the string buf with the current date as "mm/dd/yy".
  1946.  
  1947.  
  1948.         7.9.10. doint()
  1949.  
  1950.                   char inum;
  1951.                 
  1952.                   extern unsigned _rax, _rbx, _rcx, _rdx, _rsi, _rdi,
  1953.                                   _res, _rds;
  1954.                   extern char _carryf, _zerof;
  1955.  
  1956.                   _doint(inum);
  1957.  
  1958.         _rax - _rds contain the values of the corresponding 8088 internal 
  1959.         registers that are loaded and saved by _doint .  _carryf is the 
  1960.         carry flag; _zerof is the zero flag
  1961.  
  1962.         The PCCS.S Standard Library                       Page 38
  1963.  
  1964.  
  1965.         _doint will cause a software interrupt and may be used to call 
  1966.         whatever routines are available in the particular machine.  If 
  1967.         _rds is set to -1, the current value of the DS register is used.
  1968.  
  1969.         NOTE:  The following example, on an IBM-PC, would use interrupt 
  1970.         10H to print the string.
  1971.  
  1972.                 extern unsigned _rax, _rbx, _rds;
  1973.                 extern char _carryf;
  1974.                 char str[] = "Hello There!!";
  1975.                 int i;
  1976.  
  1977.                 for (i = 0; i < sizeof(str); i++) {
  1978.                         _rax = (14 << 8) + str[i];
  1979.                         _rbx = 0;
  1980.                         _rds = -1;
  1981.                         _doint(0x10);
  1982.                         }
  1983.  
  1984.  
  1985.         7.9.11. exec()
  1986.  
  1987.                   char *filename, *commandTail, Code;
  1988.  
  1989.                   Code = exec(filename, commandTail)
  1990.  
  1991.         exec will load and execute an arbitrary program.  Filename is the 
  1992.         complete pathname of the program (including the .EXE or .COM 
  1993.         suffix).  commandTail  contains the arguments to the program.  
  1994.         exec will return the completion code from the program or -1 if an 
  1995.         error occurred loading the program.  exec is in the EXEC.O file 
  1996.         provided in the distribution.
  1997.  
  1998.         NOTE: Completion codes are set for programs running under MS-DOS 
  1999.         2.0 or later versions of the operating system.  If a program 
  2000.         exits with
  2001.  
  2002.                 exit(n);
  2003.  
  2004.         the system ERRORLEVEL will be set to n.  A program that returns 
  2005.         from the main function other than by exit()sets ERRORLEVEL to 
  2006.         zero.  ERRORLEVEL can be tested with the DOS batch file IF 
  2007.         command.  See the section under 'BATCH' in the IBM 2.xx DOS 
  2008.         manual for details on the IF command.
  2009.  
  2010.         To invoke a Batch file, or a DOS built-in command, use 
  2011.         COMMAND.COM with the '/c' switch as follows.
  2012.  
  2013.                 exec("\\command.com", "/cxxx");
  2014.  
  2015.         Where xxx is one of the DOS built-in commands ( 'dir', 'copy', 
  2016.         Remember that two backslashes are required to insert a single 
  2017.         backslash in a string.  Invoking COMMAND.COM with no parameters 
  2018.         will start another DOS shell.  To return type
  2019.  
  2020.                 exit
  2021.  
  2022.         The PCCS.S Standard Library                       Page 39
  2023.  
  2024.  
  2025.  
  2026.         PCC normally allocates a stack as large as possible.  This is not 
  2027.         desirable when using exec , as little memory may be left for the 
  2028.         second program.  The -Shhhh option of the PCCL program should be 
  2029.         used to reduce the size of the stack and consequently the size of 
  2030.         the program.  Remember that the hhhh value of the option is in 
  2031.         hex and that it must be large enough for all parameters and 
  2032.         locals active at one time.  An extra 0x100 (256) bytes should 
  2033.         also be added for any system calls.
  2034.  
  2035.  
  2036.         7.9.12. exit()
  2037.  
  2038.                   char Code;
  2039.  
  2040.                   exit(Code)
  2041.  
  2042.         exit terminates the program with completion code Code.  A main() 
  2043.         procedure can also exit  with a completion code of zero by 
  2044.         returning or by "falling" through the end of the procedure.
  2045.  
  2046.         NOTE: Completion codes are set for programs running under MS-DOS 
  2047.         2.0 or later versions of the operating system.  If a program 
  2048.         exits with
  2049.  
  2050.                 exit(n);
  2051.  
  2052.         the system ERRORLEVEL will be set to n.  A program that returns 
  2053.         from the main function other than by exit()sets ERRORLEVEL to 
  2054.         zero.  ERRORLEVEL can be tested with the DOS batch file IF 
  2055.         command.  See the section under 'BATCH' in the IBM 2.xx DOS 
  2056.         manual for details on the IF command.
  2057.  
  2058.  
  2059.         7.9.13. exp()
  2060.  
  2061.                   #include <math.h>
  2062.  
  2063.                   double x, dval, exp(), exp10();
  2064.  
  2065.                   dval = exp(x);
  2066.                   dval = exp10(x);
  2067.  
  2068.         exp returns the exponential function of x; exp10 returns the 
  2069.         base 10 exponent.
  2070.  
  2071.         NOTE: exp returns a very large value when the result would 
  2072.         overflow; errno is set to ERANGE.  ERANGE is defined in math.h.
  2073.  
  2074.         The PCCS.S Standard Library                       Page 40
  2075.  
  2076.  
  2077.         7.9.14. fabs()
  2078.  
  2079.                   #include <math.h>
  2080.  
  2081.                   double dval, x;
  2082.  
  2083.                   dval = fabs(x);
  2084.  
  2085.         fabs returns |x| (absolute value).
  2086.  
  2087.  
  2088.         7.9.15. fclose()
  2089.  
  2090.                   #include <stdio.h>
  2091.                   FILE *fp;
  2092.                   int stat;
  2093.  
  2094.                   stat = fclose(fp);
  2095.  
  2096.         fclose writes any buffered data for the file fp to that file, and 
  2097.         closes the file. Returns -1 if fp is not open, or if an error 
  2098.         occurred writing the buffered data to that file.
  2099.                 
  2100.  
  2101.         7.9.16. fgetc()
  2102.  
  2103.                   #include <stdio.h>
  2104.                   FILE *fp;
  2105.                   int data;
  2106.  
  2107.                   data = fgetc(fp)
  2108.  
  2109.         fgetc returns the next character from the file fp, or -1 if an 
  2110.         error, or end of file was sensed.
  2111.  
  2112.         SEE ALSO: scanf(), fread()
  2113.  
  2114.  
  2115.         7.9.17. fgets()
  2116.  
  2117.                   #include <stdio.h>
  2118.                   FILE *fp;
  2119.                   char *cp, buf[], *fgets();
  2120.                   int len;
  2121.  
  2122.                   cp  = fgets(buf, len, fp);
  2123.  
  2124.         fgets reads the next line, but not more than len - 1 characters 
  2125.         from the file fp into buf.  The last character read into buf is 
  2126.         followed by a zero.  fgets returns buf, or 0 on end of file or an 
  2127.         error.
  2128.  
  2129.         SEE ALSO: fscanf(), fread()
  2130.  
  2131.         NOTE:  fgets returns the CR character.
  2132.  
  2133.         The PCCS.S Standard Library                       Page 41
  2134.  
  2135.  
  2136.         7.9.18. floor()
  2137.  
  2138.                   #include <math.h>
  2139.  
  2140.                   double dval, x;
  2141.  
  2142.                   dval = floor(x);
  2143.  
  2144.         floor returns the largest integer value not greater than x.
  2145.  
  2146.  
  2147.         7.9.19. fopen()
  2148.  
  2149.                   #include <stdio.h>
  2150.                   FILE *fp;
  2151.                   char *name, *method;
  2152.  
  2153.                   fp = fopen(name, method)
  2154.  
  2155.         fopen opens the file name and returns an FILE pointer that 
  2156.         identifies the file in future file operations.  Returns NULL 
  2157.         if the file can't be opened.
  2158.  
  2159.         method is a char string having one of the following values: "r" = 
  2160.         open for reading,"w" = open for writing, "a" = open for append -- 
  2161.         open for writing at end of file, or create for writing.
  2162.  
  2163.         NOTES: fopen for read access is the same as open for update; 
  2164.         write access is the same as creat for the file; append causes a 
  2165.         seek to the end of an existing file, or the creation of a new 
  2166.         file as required. 
  2167.  
  2168.         Any  of  the  functions can open the console ("CON")  or  printer 
  2169.         ("PRN").
  2170.  
  2171.  
  2172.         7.9.20. fputc()
  2173.  
  2174.                   #include <stdio.h>
  2175.                   FILE *fp;
  2176.                   char ch;
  2177.                   int data;
  2178.  
  2179.                   data = fputc(ch, fp);
  2180.  
  2181.         fputc writes ch to the file fp.  fp must have been opened 
  2182.         prior to the call.  The functions return ch, or -1 on error.
  2183.  
  2184.         SEE ALSO: printf(), fwrite()
  2185.  
  2186.         The PCCS.S Standard Library                       Page 42
  2187.  
  2188.  
  2189.         7.9.21. fputs()
  2190.  
  2191.                   #include <stdio.h>
  2192.                   FILE *fp;
  2193.                   char buf[];
  2194.                   int err;
  2195.  
  2196.                   err = fputs(buf, fp);
  2197.  
  2198.         fputs copies the null terminated string buf to the file fp.  
  2199.         fputs returns a -1 on error.
  2200.  
  2201.         SEE ALSO: fprintf()
  2202.  
  2203.         NOTE: On output, linefeed ('\n') is converted to carriage return 
  2204.         - linefeed ('\r\n').
  2205.  
  2206.  
  2207.         7.9.22. frand()
  2208.  
  2209.                   double dval;
  2210.  
  2211.                   dval = frand();
  2212.  
  2213.         frand returns the next pseudo-random number in the range from 
  2214.         0.0 to 1.0.
  2215.  
  2216.  
  2217.         7.9.23. fscanf()
  2218.  
  2219.                   #include <stdio.h>
  2220.                   FILE *fp;
  2221.                   char fcs[];
  2222.                   int num;
  2223.  
  2224.                   num = fscanf(fp, fcs [, ptr ] ... );
  2225.  
  2226.         fscanf reads from the file fp.
  2227.  
  2228.         Returns the number of items successfully scanned or -1 on end of 
  2229.         input or error.
  2230.  
  2231.         See scanf() for a how it works.
  2232.  
  2233.  
  2234.         7.9.24. getc()
  2235.  
  2236.                   #include <stdio.h>
  2237.                   FILE *fp;
  2238.                   int data;
  2239.  
  2240.                   data = getc(fp)
  2241.  
  2242.         getc  return the next character from the file fp, or -1 if an 
  2243.         error, or end of file was sensed.
  2244.  
  2245.         The PCCS.S Standard Library                       Page 43
  2246.  
  2247.  
  2248.  
  2249.         NOTE: getc is a function rather than the usual macro.
  2250.  
  2251.         getchar() will hangup reading redirected input under DOS 2.X and 
  2252.         higher.  Use getc(stdin) if the input could be redirected.
  2253.  
  2254.         SEE ALSO: scanf(), fread()
  2255.  
  2256.  
  2257.         7.9.25. getchar()
  2258.  
  2259.  
  2260.                   int data;
  2261.  
  2262.                   data = getchar();
  2263.  
  2264.         getchar  returns the next character from stdin, or -1 if an 
  2265.         error, end of file, or a CTRL-Z was found.
  2266.  
  2267.         NOTE: getchar is a function rather than the usual macro.
  2268.  
  2269.         getchar() will hangup reading redirected input under DOS 2.X and 
  2270.         higher.  Use getc(stdin) if the input could be redirected.
  2271.  
  2272.         SEE ALSO: scanf(), fread()
  2273.  
  2274.  
  2275.         7.9.26. gets()
  2276.  
  2277.                   char *cp, buf[], *gets();
  2278.                   int len, size;
  2279.  
  2280.                   cp  =  gets(buf);
  2281.                   len = _gets(buf, size);
  2282.  
  2283.         gets obtains a line-edited string from the console (stdin) into 
  2284.         buf.  During input, <ESC> means backup and start over, 
  2285.         <BACKSPACE> means delete the previous character and <RETURN> 
  2286.         means end of string.  <RETURN> is replaced in buf by a zero.  
  2287.         gets returns its argument, or 0 on end of file or an error.
  2288.  
  2289.         _gets obtains not more than size - 1 characters from the console 
  2290.         into buf.  Editing proceeds as with gets.  _gets returns the 
  2291.         number of characters obtained, or 0 on end of file or an error.
  2292.  
  2293.         SEE ALSO: fscanf(), fread()
  2294.  
  2295.         NOTE: gets and _gets don't return the CR character
  2296.  
  2297.         The PCCS.S Standard Library                       Page 44
  2298.  
  2299.  
  2300.         7.9.27. getw()
  2301.  
  2302.                   #include <stdio.h>
  2303.                   FILE *fp;
  2304.                   int data;
  2305.  
  2306.                   data = getw(fp)
  2307.  
  2308.         getw returns the next int from the file fp, or -1 if an error, or 
  2309.         end of file was sensed.
  2310.  
  2311.         SEE ALSO: scanf(), fread()
  2312.  
  2313.  
  2314.         7.9.28. in()
  2315.  
  2316.                   char ch;
  2317.                   unsigned port, wd;
  2318.  
  2319.                   ch = _inb(port);
  2320.                   wd = _inw(port);
  2321.  
  2322.         _inb  and _inw  read the byte ch  and word wd, respectively, from 
  2323.         the indicated port.
  2324.  
  2325.  
  2326.         7.9.29. index()
  2327.  
  2328.                   char *cp, *src, ch;
  2329.  
  2330.                   cp = index(src, ch);
  2331.  
  2332.         index works on null-terminated strings.  There is no test for 
  2333.         overflow.
  2334.  
  2335.         index returns a pointer to the first occurance of ch in src, 
  2336.         or 0 if ch doesn't occur.
  2337.  
  2338.  
  2339.         7.9.30. log()
  2340.  
  2341.                   #include <math.h>
  2342.  
  2343.                   double x, dval, log(), log10();
  2344.  
  2345.                   dval = log(x);
  2346.                   dval = log10(x);
  2347.  
  2348.         log  returns the natural logarithm of x;  log10 returns the base 
  2349.         10 logarithm.
  2350.  
  2351.         NOTE: log and log10 return zero when x is zero or negative; 
  2352.         errno is set to EDOM.  EDOM is defined in math.h.
  2353.  
  2354.         The PCCS.S Standard Library                       Page 45
  2355.  
  2356.  
  2357.         7.9.31. lmove()
  2358.  
  2359.                   char *sp, *tp;
  2360.                   unsigned  num, sseg, tseg;
  2361.  
  2362.                 _lmove(number, sp, sseg, tp, tseg);
  2363.  
  2364.         _lmove  moves num  bytes from the 8088 physical address at 
  2365.         sseg:sp  to tseg:tp .  For example, to move the color display 
  2366.         frame buffer at address 0xB800:0 to a local buffer ( _showds  
  2367.         provides the C program data segment  Q DS)
  2368.  
  2369.                 _lmove(4000, 0, 0xB800, buffer, _showds());
  2370.  
  2371.         NOTE:  _lmove  takes advantage of the 8088 instructions for a 
  2372.         fast data move.  It handles overlapping moves correctly so that
  2373.  
  2374.                 _lmove(3920, 0, 0xB800, 80, 0xB800);
  2375.  
  2376.         will move 0xB800:3919 to 0xB800:3999,  0xB800:3918 to 0xB800:3998 
  2377.         etc. rather than propagating 0xB800:0.
  2378.  
  2379.  
  2380.         7.9.32. longjmp()
  2381.  
  2382.                   #include <setjmp.h>
  2383.  
  2384.                   int val;
  2385.                   jmp_buf env;
  2386.  
  2387.                   longjmp(env, val);
  2388.  
  2389.         jmp_buf is defined in <setjmp.h> .  It creates an environment 
  2390.         used by setjmp for future use by longjmp .  jmp_buf is defined 
  2391.         as
  2392.                 typedef char jmp_buf[6];
  2393.  
  2394.         longjmp restores SP, BP, and return address from env and returns 
  2395.         val.  val cannot be zero.
  2396.  
  2397.         NOTE:   env  can be specified as zero,  for  compatibility  with 
  2398.         previous releases.  There can be only one "zero" env  active at 
  2399.         any time.
  2400.  
  2401.         If the environment stored in env  points into an overlay area, 
  2402.         then the overlay that called setjmp  must be resident when 
  2403.         longjmp  is called Q if another overlay is resident, then strange 
  2404.         things will happen.  It is best to call setjmp  from the root.
  2405.  
  2406.         The PCCS.S Standard Library                       Page 46
  2407.  
  2408.  
  2409.         7.9.33. open()
  2410.  
  2411.                   int handle;
  2412.                   char *name, mode;
  2413.  
  2414.                   handle = open(name, mode)
  2415.  
  2416.         open opens the file name and returns an int that identifies the 
  2417.         file in  future  file operations.  Returns -1 if the file can't 
  2418.         be opened.
  2419.  
  2420.         mode is a char having one of the following values: 0 = open for 
  2421.         reading, 1 = open for writing, 2 = open for update, and 3 = open 
  2422.         for reading (CTRLZ indicates EOF).
  2423.  
  2424.         NOTES: Any of the functions can open the console ("CON") or 
  2425.         printer ("PRN").
  2426.  
  2427.  
  2428.         7.9.34. os()
  2429.  
  2430.                   char inum, ival;
  2431.                   unsigned arg;
  2432.                 
  2433.                   ival = _os(inum, arg);
  2434.                 _doint(inum);
  2435.                 dates(buf);
  2436.                 times(buf);
  2437.  
  2438.         _os provides an elementary interrupt interface.  Under DOS, inum  
  2439.         goes into AH and arg into DX, and an int 21H, is executed.  The 
  2440.         value in AL is returned.
  2441.  
  2442.  
  2443.         7.9.35. out()
  2444.  
  2445.                   char ch;
  2446.                   unsigned port, wd;
  2447.  
  2448.                 _outb(ch, port);
  2449.                 _outw(wd, port);
  2450.  
  2451.         _outb and _outw write the byte ch  and word wd, respectively, of 
  2452.         data out to the indicated port.
  2453.  
  2454.         7.9.36. peek()
  2455.  
  2456.                   char ch, *sp;
  2457.                   unsigned  sseg;
  2458.  
  2459.  
  2460.                   ch = _peek(sp, sseg);
  2461.  
  2462.         _peek  is used to retrieve a byte ch  from the 8088 physical 
  2463.         address at sseg:sp .
  2464.  
  2465.         The PCCS.S Standard Library                       Page 47
  2466.  
  2467.  
  2468.         7.9.37. poke()
  2469.  
  2470.                   char ch, *tp;
  2471.                   unsigned  tseg;
  2472.  
  2473.                   _poke(ch, tp, tseg);
  2474.  
  2475.         _poke  is used to store the byte ch  of data to the 8088 physical 
  2476.         address at tseg:tp .
  2477.  
  2478.  
  2479.         7.9.38. pow()
  2480.  
  2481.                   #include <math.h>
  2482.  
  2483.                   double x, y, dval, pow();
  2484.  
  2485.                   dval = pow(x, y);
  2486.  
  2487.         pow  returns x ** y.
  2488.  
  2489.         NOTE: pow returns a very large value when the result would 
  2490.         overflow; errno is set to ERANGE.  pow returns zero and sets 
  2491.         errno to EDOM when the second argument is negative and not 
  2492.         integral, or when both arguments are zero.  EDOM and ERANGE are 
  2493.         defined in math.h.
  2494.  
  2495.  
  2496.  
  2497.         7.9.39. putc()
  2498.  
  2499.                   #include <stdio.h>
  2500.                   FILE *fp;
  2501.                   char ch;
  2502.                   int data;
  2503.  
  2504.                   data = putc(ch, fp);
  2505.  
  2506.         putc writes ch to the file fp .  fp must have been opened prior 
  2507.         to the call.  The functions return ch, or -1 on error.
  2508.  
  2509.         SEE ALSO: printf(), fwrite()
  2510.  
  2511.  
  2512.         7.9.40. putchar()
  2513.  
  2514.                   #include <stdio.h>
  2515.                   FILE *fp;
  2516.                   char ch;
  2517.                   int data;
  2518.  
  2519.                   data = putchar(ch);
  2520.  
  2521.         putchar writes ch  to stdout .  Linefeed ('\n') is converted to 
  2522.         carriage return - linefeed ('\r\n').  Output will stop if CTRL-S 
  2523.  
  2524.         The PCCS.S Standard Library                       Page 48
  2525.  
  2526.  
  2527.         is entered, and resume when any other key is pressed.  Each 
  2528.         output will check for a CTRL-C entry, and terminate  the program 
  2529.         if it was pressed.  putchar returns ch , or -1 on error.
  2530.  
  2531.         SEE ALSO: printf(), fwrite()
  2532.  
  2533.         NOTE:  putchar is a function rather than the usual macro.
  2534.  
  2535.  
  2536.         7.9.41. puts()
  2537.  
  2538.                   char buf[];
  2539.                   int err;
  2540.  
  2541.                   err = puts(buf);
  2542.  
  2543.         puts copies the null terminated string buf to the console 
  2544.         (stdout).  puts returns a -1 on error.
  2545.  
  2546.         SEE ALSO: printf()
  2547.  
  2548.         NOTE:  puts  doesn't append a newline.
  2549.  
  2550.         On output, linefeed ('\n') is converted to carriage return - 
  2551.         linefeed ('\r\n').  Output will stop if CTRL-S is entered, and 
  2552.         resume when any other key is pressed.  Each output will check for 
  2553.         a CTRL-C entry, and terminate  the program if it was pressed.
  2554.  
  2555.  
  2556.         7.9.42. putw()
  2557.  
  2558.                   #include <stdio.h>
  2559.                   FILE *fp;
  2560.                   int data, w;
  2561.  
  2562.                   data = putw(w, fp);
  2563.  
  2564.         putw writes the int w to the file fp .  fp must have been 
  2565.         opened prior to the call.  putw  returns w, or -1 on error.
  2566.  
  2567.         SEE ALSO: printf(), fwrite()
  2568.  
  2569.         There is no way to distinguish the return from putw(-1, fp) from 
  2570.         an error.
  2571.  
  2572.  
  2573.         7.9.43. qsort()
  2574.                   char array[];
  2575.                   int num, width, (*compare)();
  2576.  
  2577.                   qsort(array, num, width, compare);
  2578.  
  2579.         qsort is an implementation of C. A. R. Hoare's quicker-sort  
  2580.         algorithm.  It sorts an array of num elements, each width  bytes 
  2581.         wide.  compare is called with two arguments -- pointers to the 
  2582.  
  2583.         The PCCS.S Standard Library                       Page 49
  2584.  
  2585.  
  2586.         two elements being compared, and returns an integer less than, 
  2587.         equal to, or greater than zero accordingly as the first argument 
  2588.         is less than, equal to, or greater than the second argument.
  2589.  
  2590.         NOTE:  The usual function for compare is strcmp().  If you are 
  2591.         sorting anything other than strings, the following may serve as a 
  2592.         model:
  2593.  
  2594.                 int compare(left, right)
  2595.                 int *left, *right; {
  2596.                         return *left - *right;
  2597.                         }
  2598.  
  2599.                 #define TCARD    1024
  2600.                 #define ISIZE    sizeof(int)
  2601.  
  2602.                 int itab[TCARD];
  2603.  
  2604.                         qsort(itab, TCARD, ISIZE, compare);
  2605.  
  2606.         Remember that int, long, float, and double values are stored with 
  2607.         their low-order bytes first.  Thus string comparisons may not 
  2608.         produce the expected results.
  2609.  
  2610.  
  2611.         7.9.44. rand()
  2612.  
  2613.                   int ival;
  2614.  
  2615.                   ival = rand();
  2616.  
  2617.         rand returns the next pseudo-random number in the range from 0 
  2618.         to 2**15 - 1.
  2619.  
  2620.  
  2621.         7.9.45. rename()
  2622.  
  2623.                   char *oldFile, *newFile;
  2624.                   int stat;
  2625.  
  2626.                   stat = rename(oldFile, newFile);
  2627.  
  2628.         rename changes the file name oldFile to newFile.  Under DOS 2.X 
  2629.         and higher, oldFile may contain a path specification.  Returns -1 
  2630.         if oldFile is open, or if an error is detected.
  2631.  
  2632.  
  2633.         7.9.46. rindex()
  2634.  
  2635.                   char *cp, *src, ch;
  2636.  
  2637.                   cp = index(src, ch);
  2638.  
  2639.         rindex works on null-terminated strings.  There is no test for 
  2640.         overflow.
  2641.  
  2642.         The PCCS.S Standard Library                       Page 50
  2643.  
  2644.  
  2645.  
  2646.         rindex returns a pointer to the last occurance of ch in src or 0 
  2647.         if ch doesn't occur.
  2648.  
  2649.  
  2650.         7.9.47. scanf()
  2651.  
  2652.                   char fcs[];
  2653.                   int num;
  2654.  
  2655.                   num = scanf(fcs [, ptr ] ... );
  2656.  
  2657.  
  2658.         scanf reads from stdin.
  2659.  
  2660.         Returns the number of items successfully scanned.
  2661.  
  2662.         The format control string, fcs, contains: blanks or tabs, which 
  2663.         match optional whitespace (blanks, tabs, newlines, formfeeds, and 
  2664.         vertical tabs) in the input; a non-'%'  character which must 
  2665.         match the next character in the input, and conversion control 
  2666.         strings which describe the type and format of each *ptr.  
  2667.         Conversion control strings have the following format ([] enclose 
  2668.         optional entries):
  2669.  
  2670.                 %[*][width][parms]code
  2671.  
  2672.         where:  *  indicates  that  the field should be skipped  and  not 
  2673.         assigned  to a *ptr ,  width specifies the maximum field size  in 
  2674.         bytes.   Both parms and code are described below.   The  examples 
  2675.         have the following form:
  2676.  
  2677.                 | input string |  . function call . result 
  2678.  
  2679.         Character:  %[*][width]c
  2680.            String:  %[*][width]s
  2681.  
  2682.         width  specifies the number of characters to be read into the 
  2683.         array at *ptr .  The default is 1.  'c' whitespace is not 
  2684.         skipped, 's' whitespace is.
  2685.  
  2686.                 |  abc| . scanf("%3c", buf) . |  a|
  2687.                 |  abc| . scanf("%3s", buf) . |abc|
  2688.  
  2689.         Integer:  %[*][width][size]code
  2690.  
  2691.         size  equal to 'l' (lowercase 'L') specifies that *ptr  point to 
  2692.         a long, a 'h' specifies a short int .
  2693.  
  2694.         The PCCS.S Standard Library                       Page 51
  2695.  
  2696.  
  2697.         code  is one of: 'd' Q signed decimal format, 'u' Q unsigned 
  2698.         decimal format, 'o' Q unsigned octal, and 'x' Q unsigned 
  2699.         hexadecimal.
  2700.  
  2701.                 |  FF | . scanf("%x", &hex)  .  255
  2702.                 | 377 | . scanf("%o", &oct)  .  255
  2703.                 | 255 | . scanf("%u", &uns)  .  255
  2704.                 |-255 | . scanf("%ld", &lng) . -255L
  2705.  
  2706.         Floating Point:  %[*][width][size]code
  2707.  
  2708.         size  equal to 'l' (lowercase 'L') specifies that *ptr  points to 
  2709.         a double rather than a float.
  2710.  
  2711.         code  can be either 'e', 'f', or 'g' Q they all indicate floating 
  2712.         point.
  2713.  
  2714.                 | 123.45 | . scanf("%f", %flt)       . 123.45
  2715.                 | 123.45 | . scanf("%4lf%d", &d, &i) . 123.0  45
  2716.  
  2717.  
  2718.         Scanset:  %[*][width]scanset
  2719.  
  2720.         scanset  is specified by a sequence of characters enclosed by 
  2721.         brackets '[' ']'.  It reads a string, including the terminating 
  2722.         null character.  Leading whitespace is not skipped.
  2723.  
  2724.                 |123 ABC| . scanf("%[123 ]", str) . |123 |
  2725.  
  2726.         A range of contiguous characters can be specified by the first 
  2727.         and last element of the range, separated by a '-'.
  2728.  
  2729.                 |123 ABC| . scanf("%[1-3 ]", str) . |123 |
  2730.  
  2731.         If the first element of scanset  is a '^', then all characters 
  2732.         except  those specified will be read.
  2733.  
  2734.                 |123 ABC| . scanf("%[^A-C]", str) . |123 |
  2735.  
  2736.         To specify '-' or ']' in a scanset , specify it as the first 
  2737.         element.  Thus to read an integer, skip any interviening garbage, 
  2738.         and read another integer
  2739.  
  2740.                 scanf("%d%*[^-+0-9]%d", &dig1, &dig2);
  2741.  
  2742.         The PCCS.S Standard Library                       Page 52
  2743.  
  2744.  
  2745.         7.9.48. scr_aputs()
  2746.  
  2747.                   char *str, attr;
  2748.  
  2749.                   scr_aputs(str, attr);
  2750.  
  2751.         scr_aputs writes string str to the display with attribute attr.  
  2752.         '\r' moves to the begining of the line, and '\n' moves to the 
  2753.         next line.  Moving off the bottom line causes scrolling.
  2754.  
  2755.         NOTE:  scr_aputs is in the file PCIO.A.
  2756.  
  2757.  
  2758.         7.9.49. scr_ci()
  2759.  
  2760.                   char ch;
  2761.  
  2762.                   ch = scr_ci();
  2763.  
  2764.         scr_ci is like ci() but uses its own translation table for 
  2765.         command characters.  It returns the next character from the input 
  2766.         queue.
  2767.  
  2768.         NOTE:  scr_ci is in the file PCIO.A.
  2769.  
  2770.  
  2771.         7.9.50. scr_co()
  2772.  
  2773.                   char ch;
  2774.  
  2775.                   scr_co(ch);
  2776.         scr_co is the same as co() -- it writes a single character out to 
  2777.         the screen.
  2778.  
  2779.         NOTE:  scr_co is in the file PCIO.A.
  2780.  
  2781.  
  2782.         7.9.51. scr_clr()
  2783.  
  2784.                   scr_clr();
  2785.  
  2786.         scr_clr erases the entire screen and sets the cursor to the home, 
  2787.         (0,0) location.
  2788.  
  2789.         NOTE:  scr_clr is in the file PCIO.A.
  2790.  
  2791.  
  2792.         7.9.52. scr_clrl()
  2793.  
  2794.                   scr_clrl();
  2795.  
  2796.         scr_clrl erases everything from the cursor location to the end of 
  2797.         the line.
  2798.  
  2799.         NOTE:  scr_clrl is in the file PCIO.A.
  2800.  
  2801.         The PCCS.S Standard Library                       Page 53
  2802.  
  2803.  
  2804.         7.9.53. scr_cls()
  2805.  
  2806.                   scr_cls();
  2807.  
  2808.         scr_cls erases everything from the cursor location to the end  of 
  2809.         the screen.
  2810.  
  2811.         NOTE:  scr_cls is in the file PCIO.A.
  2812.  
  2813.  
  2814.         7.9.54. scr_csts()
  2815.  
  2816.                   char ch;
  2817.  
  2818.                   ch = scr_csts();
  2819.  
  2820.         scr_csts returns the next character from the queue, or 0 if no 
  2821.         character is available.  If a character is present, it is 
  2822.         equivalent to a csts() followed by a ci().
  2823.  
  2824.         NOTE:  scr_csts is in the file PCIO.A.
  2825.  
  2826.         Function keys return a zero.
  2827.  
  2828.  
  2829.         7.9.55. scr_cursoff()
  2830.  
  2831.                   scr_cursoff();
  2832.  
  2833.         scr_cursoff turns the cursor off.
  2834.  
  2835.         NOTE:  scr_cursoff is in the file PCIO.A.
  2836.  
  2837.  
  2838.         7.9.56. scr_curson()
  2839.  
  2840.                   scr_curson();
  2841.  
  2842.         scr_curson turns the cursor on.
  2843.  
  2844.         NOTE:  scr_curson is in the file PCIO.A.
  2845.  
  2846.  
  2847.         7.9.57. scr_rowcol()
  2848.  
  2849.                   int trow, tcol;
  2850.  
  2851.                   scr_rowcol(trow, tcol);
  2852.  
  2853.         scr_rowcol moves the cursor to row trow and column tcol.
  2854.  
  2855.         NOTE:  scr_rowcol is in the file PCIO.A.
  2856.  
  2857.         The PCCS.S Standard Library                       Page 54
  2858.  
  2859.  
  2860.         7.9.58. scr_scdn()
  2861.  
  2862.                   scr_scdn();
  2863.  
  2864.         scr_scdn scrolls the screen down one line, but leaves the top two 
  2865.         lines alone.
  2866.  
  2867.         NOTE:  scr_scdn is in the file PCIO.A.
  2868.  
  2869.  
  2870.         7.9.59. scr_scrdn()
  2871.  
  2872.                   int lines, frow, fcol, trow, tcol;
  2873.  
  2874.                   scr_scrdn(lines, frow, fcol, trow, tcol);
  2875.  
  2876.         scr_scrdn scrolls the given area down lines.  The area is defined 
  2877.         by the character locations (frow, fcol), (trow, tcol).
  2878.  
  2879.         NOTE:  scr_scrdn is in the file PCIO.A.
  2880.  
  2881.  
  2882.         7.9.60. scr_scrup()
  2883.  
  2884.                   int lines, frow, fcol, trow, tcol;
  2885.  
  2886.                   scr_scrup(lines, frow, fcol, trow, tcol);
  2887.  
  2888.         scr_scrup scrolls the area up lines.  The area is defined by the 
  2889.         character locations (frow, fcol), (trow, tcol).
  2890.  
  2891.         NOTE:  scr_scup is in the file PCIO.A.
  2892.  
  2893.  
  2894.         7.9.61. scr_scup()
  2895.  
  2896.                   scr_scup();
  2897.  
  2898.         scr_scup scrolls the screen up one line, but leaves the top two 
  2899.         lines alone.
  2900.  
  2901.         NOTE:  scr_scup is in the file PCIO.A.
  2902.  
  2903.  
  2904.         7.9.62. scr_setmode()
  2905.  
  2906.                   char newMode;
  2907.  
  2908.                   scr_setmode(newMode);
  2909.  
  2910.         scr_setmode  sets the mode of the color card.  newMode  must be 
  2911.         between 0 and 6.
  2912.  
  2913.         NOTE:  scr_setmode is in the file PCIO.A.
  2914.  
  2915.         The PCCS.S Standard Library                       Page 55
  2916.  
  2917.  
  2918.         scr_setmode manages the following global data.
  2919.  
  2920.                 char scr_cols;  /* number of character positions */
  2921.                 char scr_rows;  /* number of lines */
  2922.                 char scr_mode;  /* current screen mode:
  2923.                                 0 = 40 col. BW
  2924.                                 1 = 40 col. color
  2925.                                 2 = 80 col. BW
  2926.                                 3 = 80 col. color
  2927.                                 4 = 320 x 200 color graphics
  2928.                                 5 = 320 x 200 BW graphics
  2929.                                 6 = 640 x 200 BW graphics
  2930.                                 7 = 80 col. BW    */
  2931.                 char scr_page;  /* current active display page */
  2932.                 char scr_attr;  /* current character attribute.
  2933.                                 Normally 7 for white on black but
  2934.                                 can be set for any attributes
  2935.                                 see Technical Reference Manual */
  2936.  
  2937.  
  2938.         7.9.63. scr_setup()
  2939.  
  2940.                   scr_setup();
  2941.  
  2942.         scr_setup   must be called prior to any of the screen routines if 
  2943.         the screen is currently in 80 column mode or if scr_curson with a 
  2944.         monochrome display is used.
  2945.  
  2946.         NOTE:  scr_setup is in the file PCIO.A.
  2947.  
  2948.         scr_setup manages the same data as scr_setmode.
  2949.  
  2950.  
  2951.         7.9.64. scr_sinp()
  2952.  
  2953.                   char ch;
  2954.  
  2955.                   ch = scr_sinp();
  2956.  
  2957.         scr_sinp returns the character under the cursor on the screen.
  2958.  
  2959.         NOTE:  scr_sinp is in the file PCIO.A.
  2960.  
  2961.         The PCCS.S Standard Library                       Page 56
  2962.  
  2963.  
  2964.         7.9.65. setjmp()
  2965.  
  2966.                   #include <setjmp.h>
  2967.  
  2968.                   int val;
  2969.                   jmp_buf env;
  2970.  
  2971.                   val = setjmp(env);
  2972.  
  2973.         jmp_buf is defined in <setjmp.h> .  It creates an environment 
  2974.         used by setjmp  for future use by longjmp .  jmp_buf is defined 
  2975.         as
  2976.                 typedef char jmp_buf[6];
  2977.  
  2978.         setjmp  saves the current SP, BP, and return address in env.  It 
  2979.         returns a zero.
  2980.  
  2981.         NOTE:  env can be specified as zero, for compatibility with 
  2982.         previous releases.  There can be only one "zero" env  active at 
  2983.         any time.
  2984.  
  2985.         If the environment stored in env  points into an overlay area, 
  2986.         then the overlay that called setjmp  must be resident when 
  2987.         longjmp  is called -- if another overlay is resident, then 
  2988.         strange things will happen.  It is best to call setjmp  from the 
  2989.         root.
  2990.  
  2991.         setjmp's caller can tell by the returned value if control was 
  2992.         returned from setjmp(0), or from longjmp(!=0).
  2993.  
  2994.  
  2995.         7.9.66. sqrt()
  2996.  
  2997.                   #include <math.h>
  2998.  
  2999.                   double x, dval, sqrt();
  3000.  
  3001.                   dval = sqrt(x);
  3002.  
  3003.         sqrt returns the square root of x.
  3004.  
  3005.         NOTE: sqrt returns zero when x is negative; errno is set to EDOM.
  3006.         EDOM is defined in math.h.
  3007.  
  3008.  
  3009.  
  3010.         7.9.67. srand()
  3011.  
  3012.                   int seed;
  3013.  
  3014.                   srand(seed);
  3015.  
  3016.         srand sets the seed for the multiplicative congruential random 
  3017.         number generator to seed .
  3018.  
  3019.         The PCCS.S Standard Library                       Page 57
  3020.  
  3021.  
  3022.         NOTE:  The initial seed for the generator is a long.  srand  only 
  3023.         sets the low order word, so the initial generator cannot be 
  3024.         restarted.  Solution: seed the generator with your own integer 
  3025.         before any calls to rand or frand .
  3026.  
  3027.  
  3028.         7.9.68. sscanf()
  3029.  
  3030.                   char fcs[], buf[];
  3031.  
  3032.                   num = sscanf(buf, fcs [, ptr ] ... );
  3033.  
  3034.         sscanf reads from the string buf.
  3035.  
  3036.         Returns the number of items successfully scanned.
  3037.  
  3038.         See scanf() for a how it works.
  3039.  
  3040.  
  3041.         7.9.69. strcat()
  3042.  
  3043.                   char *cp, *src, *dst;
  3044.  
  3045.                   cp = strcat(dst, src);
  3046.  
  3047.         strcat works on null-terminated strings.  There is no test for 
  3048.         overflow.
  3049.  
  3050.         strcat appends a copy of src to the end of dst.
  3051.  
  3052.         Returns dst .
  3053.  
  3054.  
  3055.         7.9.70. strcmp()
  3056.  
  3057.                   char *s1, *s2;
  3058.                   int cmp;
  3059.  
  3060.                   cmp = strcmp(s1, s2);
  3061.  
  3062.         strcmp works on null-terminated strings.  There is no test for 
  3063.         overflow.
  3064.  
  3065.         strcmp  compares the two strings and returns +1, 0, or -1 
  3066.         accordingly as s1 is lexically greater than, equal to, or less 
  3067.         than s2.
  3068.  
  3069.         7.9.71. strcpy()
  3070.  
  3071.                   char *cp, *src, *dst;
  3072.  
  3073.                   cp = strcpy(dst, src);
  3074.  
  3075.         strcpy works on null-terminated strings.  There is no test for 
  3076.         overflow.
  3077.  
  3078.         The PCCS.S Standard Library                       Page 58
  3079.  
  3080.  
  3081.         strcpy copies src to dst , stopping after the null byte has been 
  3082.         transfered.
  3083.           
  3084.         Returns dst .
  3085.  
  3086.  
  3087.         7.9.72. strlen()
  3088.  
  3089.                   char *src;
  3090.                   unsigned len;
  3091.  
  3092.                   len = strlen(src);
  3093.  
  3094.         strlen works on null-terminated strings.  There is no test for 
  3095.         overflow.
  3096.  
  3097.         strlen returns the number of non-null characters in src.
  3098.  
  3099.  
  3100.         7.9.73. strncat()
  3101.  
  3102.                   char *cp, *src, *dst;
  3103.                   unsigned max;
  3104.  
  3105.                   cp = strncat(dst, src, max);
  3106.  
  3107.         strncat works on null-terminated strings.  There is no test for 
  3108.         overflow.
  3109.  
  3110.         strncat appends, at most, max  bytes of src  to the end of dst.
  3111.           
  3112.         Returns dst .
  3113.  
  3114.  
  3115.         7.9.74. strncmp()
  3116.  
  3117.                   char *s1, *s2;
  3118.                   int cmp;
  3119.                   unsigned max;
  3120.  
  3121.                   cmp = strncmp(s1, s2, max);
  3122.  
  3123.         strncmp works on null-terminated strings.  There is no test for 
  3124.         overflow.
  3125.  
  3126.         strncmp compares, at most, max  bytes of the two strings and 
  3127.         returns +1, 0, or -1 accordingly as s1 is lexically greater than, 
  3128.         equal to, or less than s2.
  3129.  
  3130.         The PCCS.S Standard Library                       Page 59
  3131.  
  3132.  
  3133.         7.9.75. strncpy()
  3134.  
  3135.                   char *cp, *src, *dst;
  3136.                   unsigned len;
  3137.  
  3138.                   cp = strncpy(dst, src, len);
  3139.  
  3140.         strncpy works on null-terminated strings.  There is no test for 
  3141.         overflow.
  3142.  
  3143.         strncpy copies exactly len bytes, from src to dst truncating or 
  3144.         null-padding as required; dst may not be null-terminated if the 
  3145.         strlen(src) >= len.
  3146.  
  3147.         Returns dst .
  3148.  
  3149.  
  3150.         7.9.76. times()
  3151.  
  3152.                   char *buf;
  3153.  
  3154.                 times(buf);
  3155.  
  3156.         times formats the string buf with the current time as "hh-mm-ss"
  3157.  
  3158.  
  3159.         7.9.77. ungetc()
  3160.  
  3161.                   #include <stdio.h>
  3162.                   FILE *fp;
  3163.                   char ch;
  3164.                   int data;
  3165.  
  3166.                   data = ungetc(ch, fp)
  3167.  
  3168.         ungetc pushes the character ch  back onto the file fp.  The next 
  3169.         call to getc or fgetc will return ch.  ungetc returns ch, or -1 
  3170.         if it can't push the character back.  fseek  clears all pushed 
  3171.         characters.  EOF (-1) can't be pushed.
  3172.  
  3173.  
  3174.         7.9.78. unlink()
  3175.  
  3176.                   char *oldFile;
  3177.                   int stat;
  3178.  
  3179.                   stat = unlink(oldFile);
  3180.  
  3181.         unlink deletes the file oldFile.  Under DOS 2.X and higher, 
  3182.         oldFile may contain a path specification.  Returns -1 if oldFile  
  3183.         doesn't exist, is open, or if an error is detected.
  3184.  
  3185.         Messages                                            Page 60
  3186.  
  3187.  
  3188.         A. Messages
  3189.  
  3190.         A.1. PCC Compiler Messages
  3191.  
  3192.         A.1.1. Banner and Termination Messages
  3193.  
  3194.         >PCC V1.2b  Copyright by Mark DeSmet 1988
  3195.         end of PCC    001A code    0012 data     1% utilization
  3196.  
  3197.         OR
  3198.  
  3199.         >PCC V1.2b  Copyright by Mark DeSmet 1988
  3200.              (various error messages)
  3201.  
  3202.             Number of Warnings = 2     Number of Errors = 5
  3203.  
  3204.         The first form of termination means the compile was successful.  
  3205.         The 'code' number is in hex and tells how many bytes of code were 
  3206.         produced.  The 'data' number is similar and tells how many bytes 
  3207.         of data were produced.  The utilization percentage is the worst 
  3208.         case of a number of compiler limits.  If it nears 100% it usually 
  3209.         means that the largest procedure should be broken into smaller 
  3210.         procedures.
  3211.  
  3212.         The second form means the compile failed.  Error messages are 
  3213.         explained in the following section.  If any errors were detected, 
  3214.         the compiler will stop trying to generate code and will stop as 
  3215.         soon as all the source has been read.  This 'syntax check' mode 
  3216.         is fast and allows the programmer to correct the program with a 
  3217.         minimum of delay.  If only warnings were detected, but no errors, 
  3218.         compilation will end normally and produce a .O file.
  3219.  
  3220.  
  3221.         A.1.2. Messages
  3222.  
  3223.         PCC produces four categories of messages: fatal errors, errors, 
  3224.         warnings and errors detected by the assembler.  Fatal errors are 
  3225.         usually caused by I/O errors but compiler errors are also in this 
  3226.         category.  When a fatal error is detected, the compiler will 
  3227.         print a message and quit.  Errors are caused by syntax errors.  
  3228.         PCC reports all such errors and then quits.  Warnings are 
  3229.         produced by correctable errors and the compiler continues.  Since 
  3230.         the compiler uses PCCA as pass 3, assembler detected errors are 
  3231.         possible but rare.  When they occur, the object module will not 
  3232.         be usable.
  3233.  
  3234.         It is easy to tell the category of an error.  After a fatal 
  3235.         error, the compiler stops without printing a termination message. 
  3236.         Errors and warnings have a distinctive format which includes the  
  3237.         word 'error' or 'warning'.  Assembler errors print the assembler 
  3238.         line that was found offensive.
  3239.  
  3240.  
  3241.         A.1.2.1. PCC Fatal Errors
  3242.  
  3243.         Messages                                            Page 61
  3244.  
  3245.  
  3246.         The pass 2 fatal errors like 'bad expression' are compiler  
  3247.         errors, but the error is usually in not detecting the problem in 
  3248.         pass 1 and printing a reasonable message.  If you get one of 
  3249.         these errors, please send your program to C Ware, but you can  
  3250.         probably find and eliminate the statement that caused the 
  3251.         problem.  Don't be frightened by seeing these errors listed; you 
  3252.         will probably never see any of them.
  3253.  
  3254.         bad  expression - this indicates a compiler error.   Printed by 
  3255.                         pass 2.
  3256.  
  3257.  
  3258.         bad GOTO target - attempt to goto something other than a label.
  3259.  
  3260.         break/case/continue/default not in switch - a case or default 
  3261.                         statement must be within a switch. A break 
  3262.                         statement must be in a while or do..while or for 
  3263.                         or switch. A continue statement must be in a 
  3264.                         while or do..while or for statement.
  3265.  
  3266.         cannot address  - illegal use of '&' operator.  Printed in pass 
  3267.                         2.
  3268.  
  3269.         cannot close <file> - the file could not be closed.   An I/O 
  3270.                         error occurred.
  3271.  
  3272.         cannot create <file> - the named file could not be created.  The 
  3273.                         name is a temporary name or the name of the 
  3274.                         object or assembler file.  This message usually 
  3275.                         means the drive is full (see 'T' option).
  3276.  
  3277.         cannot open <file> - the named source or include file could not 
  3278.                         be found.
  3279.  
  3280.         cannot read <file> - the named file could not be read.  Usually 
  3281.                         means an I/O error was detected.
  3282.  
  3283.         cannot unlink <file> - the temporary could not be deleted.  An 
  3284.                         I/O error occurred.
  3285.  
  3286.         cannot write <file> - the named file could not be written. An I/O 
  3287.                         error was detected.  Usually means the disk drive 
  3288.                         is out of space.
  3289.  
  3290.         error in register allocation - compiler error in pass 2. 
  3291.  
  3292.         divide by zero  - a constant expression evaluated to a divide by 
  3293.                         zero.  Should never happen.
  3294.  
  3295.         function too big - a function is too big for the compiler.  The 
  3296.                         'Utilization' number reflects this limit so there 
  3297.                         is normally plenty of warning.  The solution is 
  3298.                         to break large procedures into smaller ones.
  3299.  
  3300.         illegal initialization for <name> - only constant expressions and 
  3301.  
  3302.         Messages                                            Page 62
  3303.  
  3304.  
  3305.                         addresses plus or minus constant expressions can 
  3306.                         be used in initialization and the initialization 
  3307.                         must make sense.   For example
  3308.  
  3309.                         int a=b+2;
  3310.  
  3311.                         this error is fatal because it is not discovered 
  3312.                         until pass 2.
  3313.  
  3314.         no cases        - a switch must have at least one case.
  3315.  
  3316.         no input file   - PCC must be followed by the name of the source 
  3317.                         file when invoked.
  3318.  
  3319.         out of memory   - the compiler ran out of symbol space.  The 
  3320.                         'utilization' numbers warn when a program is 
  3321.                         about to exceed this or any other compiler limit.  
  3322.                         The compiler can use up to 100K, so adding memory 
  3323.                         may be a solution.  If not, the only remedy is 
  3324.                         the painful surgery required to reduce the total 
  3325.                         number of externals and locals defined at one 
  3326.                         time.
  3327.                         
  3328.         pushed          - compiler error in pass 2 code generation. It 
  3329.                         can be eliminated by simplifying the expression.
  3330.  
  3331.         too many cases  - currently, a switch statement can only contain 
  3332.                         128 case statements.
  3333.  
  3334.  
  3335.         too many fors/too many whiles - whiles, do-whiles, switches and 
  3336.                         for statements can only be nested 10 deep.
  3337.  
  3338.         stuck <register> - same as 'pushed'.
  3339.  
  3340.         too many externals - the compiler currently has a limit of 500 
  3341.                         static's or extern's.
  3342.  
  3343.  
  3344.         A.1.2.2. PCC Errors
  3345.  
  3346.         Errors are printed with the following format:
  3347.  
  3348.             23 if (i < 99 $$ {
  3349.                error:Need ()
  3350.  
  3351.         Or, if the error was detected in an include file:
  3352.  
  3353.             23 if (i < 99 $$ {
  3354.                file:<include file> error:Need ()
  3355.  
  3356.         The number preceding the source line is the line number.  To find 
  3357.         the line , edit the file and issue the command 'nnnJ' where nnn 
  3358.         is the number of the reported line.
  3359.  
  3360.         Messages                                            Page 63
  3361.  
  3362.  
  3363.         The '$$' shows how far into the line the compiler was before the 
  3364.         error was detected.  For example, the '$$' will print immediately 
  3365.         BEFORE an undefined variable.
  3366.  
  3367.         If you get a lot of errors on a compile, don't panic. A trivial 
  3368.         error probably caused the compiler to become confused.  Correct 
  3369.         the first few errors and re-compile.
  3370.  
  3371.         bad control     - the # control is illegal.
  3372.  
  3373.         bad declaration - the declaration of a variable was illegal.
  3374.  
  3375.         bad include     - the #include must be followed by "name" or 
  3376.                         <name>.
  3377.  
  3378.  
  3379.         bad label       - a colon is not preceded by a label name.
  3380.  
  3381.         bad member declare - the declaration of a member is illegal.
  3382.  
  3383.         bad member storage - an attempt was made to declare a member 
  3384.                         static or external.   Members have the storage 
  3385.                         type of their struct or union.
  3386.  
  3387.         bad parameter declare - an illegal declaration of an argument or 
  3388.                         the name of the argument was spelled differently 
  3389.                         in the procedure heading  and in the declaration.
  3390.  
  3391.         bad statement   - illegal statement.
  3392.  
  3393.         defines too deep - #define may reference another, but there is a 
  3394.                         limit. When #defines are expanded, the number of 
  3395.                         active #defines plus the number of #define 
  3396.                         arguments referenced by each cannot exceed 30.
  3397.  
  3398.         duplicate argument - an attempt was made to declare an argument 
  3399.                         twice.
  3400.  
  3401.         duplicate label - two labels have the same name.
  3402.  
  3403.         EOF within comment - end of file was found inside a comment. A 
  3404.                         '*/' is missing.
  3405.  
  3406.         field needs constant - the size of a bit field must be a constant 
  3407.                         expression with a value of 1 to 16.
  3408.  
  3409.         illegal address - attempt to use the '&' (take address of) 
  3410.                         operator on something that is not a lvalue.  
  3411.                         '&44' will generate this error.  An address can 
  3412.                         only be taken of a variable, procedure, string or 
  3413.                         label.
  3414.  
  3415.  
  3416.         illegal define  - a #define has unmatched parenthesis or the 
  3417.                         #define parameters are illegally specified.
  3418.  
  3419.         Messages                                            Page 64
  3420.  
  3421.  
  3422.  
  3423.         illegal external declaration - caused both by an illegal data or 
  3424.                         procedure declaration and improperly nested 
  3425.                         braces.  If the line is supposed to be part of a 
  3426.                         procedure (e.g. i=0;), the latter is the case.  
  3427.                         Check that every '{' outside of a comment or 
  3428.                         quoted string has a matching '}'.  Note: a prior 
  3429.                         error may have caused the compiler to lose track 
  3430.                         of a '{'.
  3431.  
  3432.         illegal indirection - caused by trying to use a char, int, 
  3433.                         unsigned, float or double as a pointer.  longs 
  3434.                         can be used as pointers but the other types 
  3435.                         cannot.
  3436.  
  3437.         include nesting too deep - includes can only be nested three deep
  3438.  
  3439.         illegal use of float - floating point numbers cannot be used as 
  3440.                         pointers.
  3441.  
  3442.         line must be constant - a #line control must be followed by a 
  3443.                         decimal constant.
  3444.  
  3445.         line too long   - the maximum line length is 128.
  3446.  
  3447.         missing ";", "(", ")", "[", "]", "{", "}", ":", "|" - the 
  3448.                         indicated "" character is needed at this point. A 
  3449.                         multitude of errors can cause these messages.  
  3450.                         The error might be fixed by sticking in the 
  3451.                         indicated character where the '$$' prints, but 
  3452.                         the item following the '$$' could be illegal.
  3453.  
  3454.         missing '       - a character constant (e.g. 'A','TEXT') can only 
  3455.                         contain one to four characters.
  3456.  
  3457.         missing argument - the argument list of a call had two adjacent 
  3458.                         commas.
  3459.  
  3460.         missing arguments - a #define was defined with arguments but used 
  3461.                         without arguments.
  3462.  
  3463.         missing dimension - an array dimension was missing in an 
  3464.                         expression or statement.  Either int x[][]; or 
  3465.                         x[]=1;.
  3466.  
  3467.         missing end of #asm - an #asm block was not ended with a #.
  3468.  
  3469.         missing expression - an expression is needed here. An example of 
  3470.                         a missing expression is i=;.
  3471.  
  3472.         missing operand - an operator without an operand was found.  An 
  3473.                         example of a missing operand is ++;
  3474.  
  3475.         missing while   - a 'do ... while' is missing the ending 'while'.
  3476.  
  3477.         Messages                                            Page 65
  3478.  
  3479.  
  3480.         must return float - a float or double function must end with a 
  3481.                         return statement that returns a value.
  3482.  
  3483.                         Note:  The compiler is too stupid to accept.
  3484.                 
  3485.                         double x(){if (1) return 1.;}.
  3486.  
  3487.         need ()         - the expression following an 'if' or 'switch' or 
  3488.                         'while' was not surrounded by parenthesis.
  3489.  
  3490.         need '{' for STRUCT initialization - the initial values used to 
  3491.                         initialize a structure must be surrounded by 
  3492.                         braces.
  3493.  
  3494.         need constant   - a 'case' prefix must be followed by an integer 
  3495.                         constant expression.
  3496.  
  3497.         need constant after #if - a #if control must be followed by a 
  3498.                         constant expression.
  3499.  
  3500.         need label      - a goto must reference a label.
  3501.  
  3502.         need lval       - a lvalue is needed here. An lvalue is, roughly, 
  3503.                         something that can be changed with an assignment.  
  3504.                         The statement: 2=4; will produce this error.
  3505.  
  3506.         need member     - the '.' or '->' operators were followed by 
  3507.                         something other than a member name.
  3508.  
  3509.         need structure  - the name prior to a '.' operator is not the 
  3510.                         name of a struct or union.
  3511.  
  3512.         not an identifier - #ifdef, #ifndef and #undef controls must 
  3513.                         reference a #define value;.
  3514.  
  3515.         not defined     - #undef controls must reference a #define 
  3516.                         value;.
  3517.  
  3518.         only STATIC and EXTERN allowed at this level - an attempt was 
  3519.                         made to declare an 'auto' outside of a procedure.
  3520.  
  3521.         parameters cannot span lines - the arguments to a #define must 
  3522.                         all be on the same line.
  3523.  
  3524.         return lacks argument - if a function is declared as returning a 
  3525.                         value then "return;" is illegal.  Use "return 0;" 
  3526.                         if the value is unimportant.
  3527.  
  3528.         sorry, must have dimension for locals - the compiler does not 
  3529.                         accept char a[]={1,2,3}; and similar  for auto 
  3530.                         variables.  Declare the variable static or 
  3531.                         include an explicit dimension.
  3532.  
  3533.         sorry, no string initialization of AUTO - the compiler cannot 
  3534.                         accept char a[]="abc"; and similar for auto 
  3535.  
  3536.         Messages                                            Page 66
  3537.  
  3538.  
  3539.                         variables.  Declare the variable static if 
  3540.                         possible, otherwise use _move.
  3541.  
  3542.         string too long - a string cannot exceed 200 characters.  Usually 
  3543.                         means that a '"' is missing.
  3544.  
  3545.         undefined structure - a  pointer to an undefined structure cannot 
  3546.                         be added to.
  3547.  
  3548.         unknown control - the word following a '#' is not a control word.  
  3549.                         '#while' would cause this error.
  3550.  
  3551.         unmatched "     - either the end of line or end of file was found 
  3552.                         in a string.  Usually means that a " is missing. 
  3553.                         if your string is too long for one line, continue 
  3554.                         with a \ (backslash) at the end of a line and 
  3555.                         continue in column one of the next.  If you want 
  3556.                         a new line in a string, use \n.
  3557.  
  3558.         wrong number of arguments - a #define was used with the wrong 
  3559.                         number of arguments.
  3560.  
  3561.  
  3562.         A.1.2.3. PCC Warnings
  3563.  
  3564.         There are currently only two warnings. Warnings indicate 
  3565.         suspicious code that is probably OK.
  3566.  
  3567.         conflicting types - an external or static was declared twice with 
  3568.                         different types.  Usually caused by an include 
  3569.                         file declaring a variable incorrectly or by a 
  3570.                         program such as:
  3571.  
  3572.                         main() {
  3573.                                 char ch;
  3574.          
  3575.                                 ch=zipit();
  3576.                                 }
  3577.          
  3578.                         char zipit(ch)
  3579.                         char ch; {
  3580.  
  3581.                                 return ch;
  3582.                                 }
  3583.  
  3584.                         the call of zipit implicitly declares it to be a 
  3585.                         function  returning an integer.  The line 'char 
  3586.                         zipit(ch)' would be flagged as an error.  The fix 
  3587.                         is to include:
  3588.  
  3589.                         char zipit();
  3590.  
  3591.                         above the call so the function is declared 
  3592.                         correctly before use.
  3593.  
  3594.         Messages                                            Page 67
  3595.  
  3596.  
  3597.         undefined variable - the variable has not been defined.  It is 
  3598.                         assumed to be an auto int.
  3599.  
  3600.  
  3601.  
  3602.         A.1.2.4. PCCA Errors ( from PCC Execution )
  3603.  
  3604.         In theory, any PCCA error message can be produced by a PCC 
  3605.         compile gone bonkers but I have only seen the 'cannot write 
  3606.         <name>' errors caused by lack of disk space.
  3607.  
  3608.  
  3609.  
  3610.  
  3611.         A.2. PCCA Assembler Messages
  3612.  
  3613.         A.2.1. Banner and Termination Messages
  3614.  
  3615.         >PCCA PCC Assembler V1.2b Copyright by Mark DeSmet 1988
  3616.  
  3617.             (various error messages)
  3618.  
  3619.         end of PCCA  0016 code  0000 data  1% utilization
  3620.  
  3621.         The 'code' number is in hex and tells how many bytes of code were 
  3622.         produced.  The 'data' number is similar and tells how many bytes 
  3623.         of data were produced.  The utilization percentage shows how full 
  3624.         the symbol table was.
  3625.  
  3626.         Sample of list output:
  3627.  
  3628.         PCCA Assembler    BLIP.A
  3629.                          1      ;TOUPPER.A convert a charcter to upper case
  3630.                          2
  3631.                          3      CSEG
  3632.                          4      PUBLIC TOUPPER
  3633.                          5
  3634.                          6      ;  character = toupper(character)
  3635.                          7
  3636.         0000 5A          8      TOUPPER:POP     DX      ;RETURN ADDRESS
  3637.         0001 58          9            POP       AX      ;CHARACTER
  3638.         0002 3C61       10            CMP       AL,'a'  ;IF LOWER THAN 'a'
  3639.                         11            JC        TO_DONE ;DO NOTHING
  3640.         0004 3C7B       12            CMP       AL,'z'  ;OR IF ABOVE 'z'
  3641.                         13            JNC       TO_DONE ;DO NOTHING
  3642.         0006 2C20       14            SUB       AL,'a'-'A' ;ELSE ADJUST
  3643.         0008 B400       15      TO_DONE:MOV     AH,0    ;RETURN AN INT
  3644.         000A FFE2       16            JMP       DX      ;RETURN
  3645.  
  3646.  
  3647.  
  3648.         A.2.2. Messages Produced by PCCA
  3649.  
  3650.         PCCA prints two categories of messages: fatal errors and errors.  
  3651.         As with PCC, the fatal errors are caused by I/O errors or 
  3652.  
  3653.         Messages                                            Page 68
  3654.  
  3655.  
  3656.         similar.  Errors are simply syntax errors in using the language.   
  3657.         When a fatal error is detected, PCCA prints a message and stops.  
  3658.         An error does not stop the assembler, but it stops writing the 
  3659.         object module to run faster.  If errors are detected, the object 
  3660.         module is never good.
  3661.  
  3662.  
  3663.         A.2.2.1. Fatal Errors From PCCA
  3664.  
  3665.         cannot close <file> - the file could not be closed. An I/O error 
  3666.                         occurred.
  3667.  
  3668.         cannot create <file> - the named file could not be created. The 
  3669.                         name is a temporary name or the name of the 
  3670.                         object or list file.  This message usually means 
  3671.                         the drive is full (see 'T' option).
  3672.  
  3673.         cannot open <file> - the named source or include file could not 
  3674.                         be found.
  3675.  
  3676.         cannot read <file> - the named file could not be read. Usually 
  3677.                         means an I/O error was detected.
  3678.  
  3679.         cannot unlink <file> - the temporary file could not be deleted. 
  3680.                         An I/O error occurred.
  3681.  
  3682.         cannot write <file> - the named file could not be written. An I/O 
  3683.                         error was detected.  Usually means the disk drive 
  3684.                         is out of space.
  3685.  
  3686.         internal error in jump optimization - the assembler became 
  3687.                         confused optimizing branches.
  3688.  
  3689.         no input file   - no filename followed the PCCA when invoked.
  3690.  
  3691.         too  many labels - only 1000 names and labels are allowed.
  3692.  
  3693.         too many symbols - the assembler ran out of symbol space.  The 
  3694.                         source program should be broken into smaller 
  3695.                         modules.
  3696.  
  3697.  
  3698.  
  3699.         A.2.2.2. Errors from PCCA
  3700.  
  3701.         Error messages have the form:
  3702.  
  3703.             44  mov  #44,a3
  3704.             error: illegal mnemonic
  3705.  
  3706.         or, if the error was found in an include file:
  3707.  
  3708.             44  mov  #44,a3
  3709.             file:2:SCREEN.A  error: illegal mnemonic
  3710.  
  3711.         Messages                                            Page 69
  3712.  
  3713.  
  3714.         The messages are:
  3715.  
  3716.  
  3717.         address must be in DSEG - address constants  can only be in DSEG, 
  3718.                         because constants in CSEG are not fixed up at run 
  3719.                         time.
  3720.  
  3721.         bad DS value    - a constant expression must follow the DS.
  3722.  
  3723.         bad include     - the correct form for an include statement is:
  3724.  
  3725.                         include "filename"
  3726.  
  3727.         bad LINE value  - the line statement should be followed by a 
  3728.                         constant.
  3729.  
  3730.         cannot label PUBLIC - a 'public' statement cannot have a label.
  3731.  
  3732.         data offset must be an unsigned - an attempt was made to use an 
  3733.                         offset in a byte or long constant.  
  3734.  
  3735.         DS must have label - storage cannot be reserved without a name.
  3736.  
  3737.         DS must be in DSEG - storage can only be reserved in DSEG.
  3738.  
  3739.         duplicate label - the label on the line was defined previously.
  3740.  
  3741.         equate too deep - an 'equ' may reference a prior one, but only to 
  3742.                         a depth of four.
  3743.  
  3744.         illegal expression - the expression had an illegal operator or is 
  3745.                         somehow invalid.
  3746.  
  3747.         illegal operand - an operand had a type that was not legal in 
  3748.                         that context.
  3749.  
  3750.         illegal reserved word - a reserved word was found in the wrong 
  3751.                         context.
  3752.  
  3753.         illegal ST value - the index to a floating point stack element 
  3754.                         must be in the range 0 to 7.
  3755.  
  3756.         incorrect type  - only 'byte', 'word', 'dword', and 'tbyte', are 
  3757.                         allowed following the colon to type a public.
  3758.  
  3759.         impossible arithmetic - an arithmetic operation has operands 
  3760.                         incompatible with the 8086 architecture.
  3761.  
  3762.                         example:
  3763.  
  3764.                         add word [bx], word[si]
  3765.  
  3766.         in wrong segment - a variable or label is being defined in a 
  3767.                         segment different than the segment of the 
  3768.                         'public' statement.  Remember that 'public' 
  3769.  
  3770.  
  3771.  
  3772.         Messages                                            Page 70
  3773.  
  3774.  
  3775.                         statements must be in the correct segment, 
  3776.                         following 'dseg' or 'cseg' as appropriate.
  3777.  
  3778.         invalid BYTE constant - a byte constant was needed, but something 
  3779.                         else was found.
  3780.  
  3781.         invalid constant - the instruction needed a constant and 
  3782.                         something else was found.
  3783.  
  3784.         invalid DD constant - the value of a 'DD' must be a constant 
  3785.                         expression.
  3786.  
  3787.         invalid DW constant - the value of a 'DW' must be a constant 
  3788.                         expression or a variable name.  In the latter 
  3789.                         case, offset is assumed.  The statement:
  3790.  
  3791.                         dw   offset  zip
  3792.  
  3793.                         is illegal since offset is already implied.  Just 
  3794.                         use:
  3795.  
  3796.                         dw   zip
  3797.  
  3798.         invalid offset  - an offset of the expression cannot be taken.
  3799.  
  3800.         line too long   - the maximum input line to PCCA is 110 
  3801.                         characters.
  3802.  
  3803.         mismatched types - the types of the two operands must agree.
  3804.  
  3805.                         example:
  3806.  
  3807.                         db      chr
  3808.                         add     ax,bl           ;illegal
  3809.                         add     chr,ax          ;illegal
  3810.                         add     word chr,ax     ;legal
  3811.  
  3812.  
  3813.         misplaced reserved word - a reserved word was found in an 
  3814.                         expression.
  3815.  
  3816.         missing :       - the '?' operator was missing the colon part.
  3817.  
  3818.         missing )       - mismatched parenthesis.
  3819.  
  3820.         missing ]       - mismatched braces in an address expression.
  3821.  
  3822.         missing ':'     - labels to instructions must be followed by a 
  3823.                         colon.  This message also prints when a mnemonic 
  3824.                         is misspelled.  The assembler thinks that the bad 
  3825.                         mnemonic is a label without a colon.
  3826.  
  3827.         missing EQU name - an equate statement lacks a name.
  3828.  
  3829.         missing type    - the memory reference needs a type.  In the case 
  3830.  
  3831.         Messages                                            Page 71
  3832.  
  3833.  
  3834.                         of 'public's defined elsewhere, the type can be 
  3835.                         supplied by ':byte' or ':word' on the public 
  3836.                         statement.  In the case of anonymous references, 
  3837.                         the 'byte' or 'word' keyword must be used.
  3838.  
  3839.                         example:
  3840.  
  3841.                         public  a:byte
  3842.                         inc     a               ; illegal
  3843.                         inc     byte a          ; legal
  3844.                         inc     es:[bx]         ; illegal
  3845.                         inc     es:word[bx]     ; legal
  3846.  
  3847.         need constant   - something other than a constant expression 
  3848.                         followed a 'ret'.
  3849.  
  3850.         need label      - a jump relative was made to something other 
  3851.                         than a label.  'jmp's may be indirect but 'jz's 
  3852.                         etc. can only jump to a label.
  3853.  
  3854.         nested include  - an included file may not include another.
  3855.  
  3856.         not a label     - only names can be public.
  3857.  
  3858.         RB must have label - a 'RB' statement must have a label.
  3859.  
  3860.         RB must be in DS - 'RB's must follow a DSEG directive as they can 
  3861.                         only be in the data segment.  'DB's can be in the 
  3862.                         code segment.
  3863.  
  3864.         RW must be in DS - as above.
  3865.  
  3866.         too many arguments - the instruction had more operands than 
  3867.                         allowed or the last operand contains an illegal 
  3868.                         op-code.
  3869.  
  3870.         undefined variable <name> - the name is referred to but not 
  3871.                         defined or listed as public.
  3872.  
  3873.         unknown mnemonic - the mnemonic is illegal.
  3874.  
  3875.         A.3. PCCL Messages
  3876.  
  3877.  
  3878.         A.3.1. Banner and Termination Messages
  3879.  
  3880.         PCCL  Linker for PCC and PCCA V1.2b Copyright by Mark DeSmet 1988
  3881.         end of PCCL        9% utilization
  3882.  
  3883.  
  3884.         A.3.2. Warnings from PCCL
  3885.  
  3886.         undefined PUBLIC - <name> - the name is referenced, but not 
  3887.  
  3888.         Messages                                            Page 72
  3889.  
  3890.  
  3891.                         defined in any module.  PCCL will complete and 
  3892.                         the resulting .EXE module may execute as long as 
  3893.                         the undefined PUBLICs are not referenced.  If 
  3894.                         they are referenced, then the result is 
  3895.                         undefined.
  3896.  
  3897.  
  3898.         A.3.3. Fatal Errors from PCCL 
  3899.  
  3900.         PCCL prints the message, prints 'PCCL abandoned' and quits.
  3901.  
  3902.         bad argument    - an argument is illegal.
  3903.  
  3904.         bad object file<name> - the object or library file contains an 
  3905.                         illegal record.
  3906.  
  3907.         bad stack option - the 'S' option should be followed by one to 
  3908.                         four hex digits.
  3909.  
  3910.         cannot close <file> - I/O error occurred.
  3911.  
  3912.         cannot create <file> - I/O error or disk out of room.  On MS-DOS 
  3913.                         2.0 and later, make sure that the CONFIG.SYS file 
  3914.                         contains a FILES=20 command.
  3915.  
  3916.         cannot open <file> - the object file could not be found.  On MS-
  3917.                         DOS 2.0 and later, make sure that the CONFIG.SYS 
  3918.                         file contains a FILES=20 command.
  3919.  
  3920.         cannot read <file> - I/O error occurred.
  3921.  
  3922.         cannot seek <file> - I/O error occurred.
  3923.  
  3924.         cannot write <file> - I/O error or disk out of room.
  3925.  
  3926.         different segments for - <name> - the public is declared in 
  3927.                         different segments in different modules.  
  3928.                         Probably both as a function and as a variable.
  3929.  
  3930.         illegal overlay number - in the overlay options -Vnn and -Mnn, 
  3931.                         the value nn must be between 1 and 39 in 
  3932.                         ascending, consecutive order.
  3933.  
  3934.         multiply defined <name> - the same public appears in two modules.
  3935.  
  3936.         over 100 arguments - PCCL only allows 100 arguments, including 
  3937.                         arguments in -F files. 
  3938.  
  3939.         over 64K code   - a segment has over 64K of code. See the 
  3940.                         description of PCCL overlay support.
  3941.  
  3942.         over 64K data   - the resultant program has over 64K of data. 
  3943.                         This is not supported.  You will have to move 
  3944.                         some data to locals or use overlays.
  3945.  
  3946.  
  3947.         Messages                                            Page 73
  3948.  
  3949.  
  3950.         over 300 modules - only 300 modules can be linked together.  The 
  3951.                         supplied library only contains about 60 modules.
  3952.  
  3953.         too many filenames - there are only 2000 bytes reserved for all 
  3954.                         filenames.
  3955.  
  3956.         too many labels in <name> - a module in the named file had over 
  3957.                         1000 labels.
  3958.  
  3959.         too many total PUBLICS in <name> - symbol table has overflowed.  
  3960.                         The named file was being read when the overflow 
  3961.                         occurred.
  3962.  
  3963.         Order Form                                          Page 74
  3964.  
  3965.  
  3966.         B. Order Form
  3967.  
  3968.         Remit to: C Ware Corporation
  3969.                   P.O. Box 428
  3970.                   Paso Robles, CA 94447
  3971.  
  3972.         PCC version 1.2b
  3973.  
  3974.         You can also order by phone using your P.O.#, Mastercard or VISA.  
  3975.         (805) 239-4620, 9:00 a.m. - 4:00 p.m., PST ONLY.
  3976.  
  3977.         ____ PCC Registration .................... @ $ 30.00 ea  $ ______
  3978.              (includes registration software -OR- 
  3979.               latest version of PCC)
  3980.  
  3981.         ____ UPGRADE to the newest version .......  @ $ 8.00 ea  $ ______
  3982.              (includes latest version of the program diskette,
  3983.               with documentation on the disk.)
  3984.  
  3985.         Orders are normally shipped by USPS at no additional charge.
  3986.  
  3987.         For UPS shipment, please add $3.00            $  3.00 ea  $ _____
  3988.  
  3989.                                                        Subtotal    ______
  3990.  
  3991.                                                   Less Discount    ______
  3992.  
  3993.                                                            Total $ ______
  3994.  
  3995.  
  3996.  
  3997.         Payment by:  [ ] Check  [ ] MC  [ ] Visa  [ ] PO # ______________
  3998.  
  3999.         Name: ___________________________________________________________
  4000.  
  4001.         Company: ________________________________________________________
  4002.  
  4003.         Address: ________________________________________________________
  4004.  
  4005.                : ________________________________________________________
  4006.  
  4007.                : ________________________________________________________
  4008.  
  4009.         Day Phone: _______________________ Eve: _________________________
  4010.  
  4011.          Card #: _______________________________ Exp. Date: _____________
  4012.  
  4013.         Signature of cardholder: ________________________________________
  4014.  
  4015.         User Comments                                       Page 75
  4016.  
  4017.  
  4018.         C. User Comments
  4019.  
  4020.         I acquired PCC from
  4021.                 [ ] - Friend                    [ ] - Software product
  4022.                 [ ] - Computer Club             [ ] - Computer Store
  4023.                 [ ] - Data Base Service         [ ] - Electronic BBS
  4024.                 [ ] - Other - Please Specify ____________________________
  4025.  
  4026.         We would also appreciate any input you would care to give 
  4027.         concerning PCC.  If you have any ideas or comments that would 
  4028.         make PCC a better program, then please let us know.
  4029.  
  4030.         We value your comments!
  4031.  
  4032.         Comments and/or suggestions:
  4033.         ________________________________________________________________
  4034.  
  4035.         ________________________________________________________________
  4036.  
  4037.         ________________________________________________________________
  4038.  
  4039.         ________________________________________________________________
  4040.  
  4041.         ________________________________________________________________
  4042.  
  4043.         ________________________________________________________________
  4044.  
  4045.         ________________________________________________________________
  4046.  
  4047.         ________________________________________________________________
  4048.  
  4049.         ________________________________________________________________
  4050.  
  4051.         ________________________________________________________________
  4052.  
  4053.         ________________________________________________________________
  4054.  
  4055.         ________________________________________________________________
  4056.  
  4057.         ________________________________________________________________
  4058.  
  4059.                                TABLE OF CONTENTS
  4060.  
  4061.  
  4062.                        T A B L E   O F   C O N T E N T S 
  4063.  
  4064.           1. The Legal Stuff............................................1
  4065.              1.1. License...............................................2
  4066.              1.2. Support Policy........................................2
  4067.              1.3. DISCLAIMER............................................3
  4068.              1.4. FOREIGN RESHIPMENT LIABILITY..........................3
  4069.              1.5. LIMITED WARRANTY                                                              ......................................3
  4070.              1.6. LIMITATIONS OF REMEDIES...............................3
  4071.              1.7. General...............................................4
  4072.              1.8. TRADEMARKS............................................4
  4073.              1.9. ORDERING INFORMATION..................................4
  4074.              1.10. Use by Educational Institutions......................5
  4075.              1.11. Corporate, Business, Government and Commercial Use...5
  4076.  
  4077.           2. Preface....................................................7
  4078.  
  4079.           3. An Introduction To PCC.....................................8
  4080.              3.1. Using Text, Book, Magazine or Download source code....8
  4081.              3.2. Getting Started.......................................9
  4082.              3.3. PCC Files.............................................9
  4083.              3.4. Basic System.........................................10
  4084.              3.5. Setting Up DOS 2.xx, 3.xx, ..........................10
  4085.              3.6. RAM DISK.............................................11
  4086.              3.7. Completion Codes.....................................11
  4087.  
  4088.           4. PCC -- The Personal C Compiler............................13
  4089.              4.1. Introduction.........................................13
  4090.              4.2. Examples.............................................14
  4091.              4.3. The C Language.......................................15
  4092.                   4.3.1. Preprocessor directives.......................15
  4093.                   4.3.2. Data Types....................................15
  4094.              4.4. Extensions...........................................16
  4095.                   4.4.1. Forward References............................18
  4096.                   4.4.2. Externs.......................................18
  4097.                   4.4.3. Macros........................................20
  4098.                   4.4.4. Strings.......................................20
  4099.  
  4100.           5. The PCCA 8088 Assembler...................................21
  4101.              5.1. Introduction.........................................21
  4102.              5.2. Invocation...........................................21
  4103.              5.3. Example..............................................21
  4104.  
  4105.           6. The PCCL Object File Linker...............................23
  4106.              6.1. Introduction.........................................23
  4107.              6.2. Invocation...........................................23
  4108.              6.3. Examples.............................................24
  4109.              6.4. Space Considerations.................................25
  4110.              6.5. Overlays.............................................25
  4111.              6.6. Libraries............................................27
  4112.  
  4113.                                TABLE OF CONTENTS
  4114.  
  4115.  
  4116.           7. The PCCS.S Standard Library...............................28
  4117.              7.1. Introduction.........................................28
  4118.              7.2. Names................................................28
  4119.              7.3. Program Initialization...............................28
  4120.              7.4. Calling Conventions..................................29
  4121.              7.5. LIBRARY CONVENTIONS..................................31
  4122.              7.6. Disk Input/Output Routines...........................32
  4123.              7.7. Math Routines........................................33
  4124.              7.8. IBM-PC Screen and Keyboard Interface.................34
  4125.              7.9. Standard Library Functions...........................34
  4126.                   7.9.1. abs().........................................34
  4127.                   7.9.2. atoi()........................................34
  4128.                   7.9.3. atof()........................................35
  4129.                   7.9.4. atol()........................................35
  4130.                   7.9.5. ceil()........................................36
  4131.                   7.9.6. chain().......................................36
  4132.                   7.9.7. close().......................................37
  4133.                   7.9.8. creat().......................................37
  4134.                   7.9.9. dates().......................................37
  4135.                   7.9.10. doint()......................................37
  4136.                   7.9.11. exec().......................................38
  4137.                   7.9.12. exit().......................................39
  4138.                   7.9.13. exp()........................................39
  4139.                   7.9.14. fabs().......................................40
  4140.                   7.9.15. fclose().....................................40
  4141.                   7.9.16. fgetc()......................................40
  4142.                   7.9.17. fgets()......................................40
  4143.                   7.9.18. floor()......................................41
  4144.                   7.9.19. fopen()......................................41
  4145.                   7.9.20. fputc()......................................41
  4146.                   7.9.21. fputs()......................................42
  4147.                   7.9.22. frand()......................................42
  4148.                   7.9.23. fscanf().....................................42
  4149.                   7.9.24. getc().......................................42
  4150.                   7.9.25. getchar()....................................43
  4151.                   7.9.26. gets().......................................43
  4152.                   7.9.27. getw().......................................44
  4153.                   7.9.28. in().........................................44
  4154.                   7.9.29. index()......................................44
  4155.                   7.9.30. log()........................................44
  4156.                   7.9.31. lmove()......................................45
  4157.                   7.9.32. longjmp()....................................45
  4158.                   7.9.33. open().......................................46
  4159.                   7.9.34. os().........................................46
  4160.                   7.9.35. out()........................................46
  4161.                   7.9.36. peek().......................................46
  4162.                   7.9.37. poke().......................................47
  4163.                   7.9.38. pow()........................................47
  4164.                   7.9.39. putc().......................................47
  4165.                   7.9.40. putchar()....................................47
  4166.                   7.9.41. puts().......................................48
  4167.                   7.9.42. putw().......................................48
  4168.                   7.9.43. qsort()......................................48
  4169.                   7.9.44. rand().......................................49
  4170.                   7.9.45. rename().....................................49
  4171.  
  4172.                                TABLE OF CONTENTS
  4173.  
  4174.  
  4175.                   7.9.46. rindex().....................................49
  4176.                   7.9.47. scanf()......................................50
  4177.                   7.9.48. scr_aputs()..................................52
  4178.                   7.9.49. scr_ci().....................................52
  4179.                   7.9.50. scr_co().....................................52
  4180.                   7.9.51. scr_clr()....................................52
  4181.                   7.9.52. scr_clrl()...................................52
  4182.                   7.9.53. scr_cls()....................................53
  4183.                   7.9.54. scr_csts()...................................53
  4184.                   7.9.55. scr_cursoff()................................53
  4185.                   7.9.56. scr_curson().................................53
  4186.                   7.9.57. scr_rowcol().................................53
  4187.                   7.9.58. scr_scdn()...................................54
  4188.                   7.9.59. scr_scrdn()..................................54
  4189.                   7.9.60. scr_scrup()..................................54
  4190.                   7.9.61. scr_scup()...................................54
  4191.                   7.9.62. scr_setmode()................................54
  4192.                   7.9.63. scr_setup()..................................55
  4193.                   7.9.64. scr_sinp()...................................55
  4194.                   7.9.65. setjmp().....................................56
  4195.                   7.9.66. sqrt().......................................56
  4196.                   7.9.67. srand()......................................56
  4197.                   7.9.68. sscanf().....................................57
  4198.                   7.9.69. strcat().....................................57
  4199.                   7.9.70. strcmp().....................................57
  4200.                   7.9.71. strcpy().....................................57
  4201.                   7.9.72. strlen().....................................58
  4202.                   7.9.73. strncat()....................................58
  4203.                   7.9.74. strncmp()....................................58
  4204.                   7.9.75. strncpy()....................................59
  4205.                   7.9.76. times()......................................59
  4206.                   7.9.77. ungetc().....................................59
  4207.                   7.9.78. unlink().....................................59
  4208.  
  4209.  
  4210.         
  4211.         Appendices
  4212.  
  4213.           A. Messages..................................................60
  4214.              A.1. PCC Compiler Messages................................60
  4215.                   A.1.1. Banner and Termination Messages...............60
  4216.                   A.1.2. Messages......................................60
  4217.                          A.1.2.1. PCC Fatal Errors.....................60
  4218.                          A.1.2.2. PCC Errors...........................62
  4219.                          A.1.2.3. PCC Warnings.........................66
  4220.                          A.1.2.4. PCCA Errors ( from PCC Execution )...67
  4221.              A.2. PCCA Assembler Messages..............................67
  4222.                   A.2.1. Banner and Termination Messages...............67
  4223.                   A.2.2. Messages Produced by PCCA.....................67
  4224.                          A.2.2.1. Fatal Errors From PCCA...............68
  4225.                          A.2.2.2. Errors from PCCA.....................68
  4226.              A.3. PCCL Messages........................................71
  4227.                   A.3.1. Banner and Termination Messages...............71
  4228.                   A.3.2. Warnings from PCCL............................71
  4229.                   A.3.3. Fatal Errors from PCCL .......................72
  4230.  
  4231.                                TABLE OF CONTENTS
  4232.  
  4233.  
  4234.           B. Order Form................................................74
  4235.  
  4236.           C. User Comments.............................................75
  4237.  
  4238.              index.....................................................76
  4239.  
  4240.                                TABLE OF CONTENTS
  4241.  
  4242.  
  4243.                          L I S T   O F   F I G U R E S
  4244.  
  4245.          7-1: Initial Memory Layout....................................29
  4246.  
  4247.  
  4248.  
  4249.  
  4250.          index
  4251.  
  4252.         A
  4253.         abs(), 34
  4254.         An Introduction To PCC, 8
  4255.         atof(), 35
  4256.         atoi(), 34
  4257.         atol(), 35
  4258.  
  4259.         B
  4260.         Banner and Termination Messages, 60, 67, 71
  4261.         Banner and Termination Messages:, 73
  4262.         Basic System, 10
  4263.  
  4264.         C
  4265.         Calling Conventions, 29
  4266.         ceil(), 36
  4267.         chain(), 36
  4268.         close(), 37
  4269.         Completion Codes, 11
  4270.         Corporate
  4271.            Business, Government and Commercial Use, 5
  4272.         creat(), 37
  4273.  
  4274.         D
  4275.         Data Types, 15
  4276.         dates(), 37
  4277.         DISCLAIMER, 3
  4278.         Disk Input/Output Routines, 32
  4279.         doint(), 37
  4280.  
  4281.         E
  4282.         Errors from PCCA, 68
  4283.         Example, 21
  4284.         Examples, 14, 24
  4285.         exec(), 38
  4286.         exit(), 39
  4287.         exp(), 39
  4288.         Extensions, 16
  4289.         Externs, 18
  4290.  
  4291.         F
  4292.         fabs(), 40
  4293.         Fatal Errors From PCCA, 68
  4294.         Fatal Errors from PCCL, 72
  4295.         fclose(), 40
  4296.         fgetc(), 40
  4297.         fgets(), 40
  4298.         floor(), 41
  4299.         fopen(), 41
  4300.         FOREIGN RESHIPMENT LIABILITY, 3
  4301.  
  4302.  
  4303.  
  4304.  
  4305.         Forward References, 18
  4306.         fputc(), 41
  4307.         fputs(), 42
  4308.         frand(), 42
  4309.         fscanf(), 42
  4310.  
  4311.         G
  4312.         General, 4
  4313.         getc(), 42
  4314.         getchar(), 43
  4315.         gets(), 43
  4316.         Getting Started, 9
  4317.         getw(), 44
  4318.  
  4319.         I
  4320.         IBM-PC Screen and Keyboard Interface, 34
  4321.         in(), 44
  4322.         index(), 44
  4323.         Introduction, 13, 21, 23, 28
  4324.         Invocation, 21, 23
  4325.  
  4326.         L
  4327.         Libraries, 27
  4328.         LIBRARY CONVENTIONS, 31
  4329.         License, 2
  4330.         LIMITATIONS OF REMEDIES, 3
  4331.         LIMITED WARRANTY                                                                , 3
  4332.         lmove(), 45
  4333.         log(), 44
  4334.         longjmp(), 45
  4335.  
  4336.         M
  4337.         Macros, 20
  4338.         Math Routines, 33
  4339.         Messages, 60
  4340.         Messages Produced by PCCA, 67
  4341.  
  4342.         N
  4343.         Names, 28
  4344.  
  4345.         O
  4346.         open(), 46
  4347.         Order Form, 75
  4348.         ORDERING INFORMATION, 4
  4349.         os(), 46
  4350.         out(), 46
  4351.         Overlays, 25
  4352.  
  4353.         P
  4354.         PCC -- The Personal C Compiler, 13
  4355.         PCC Compiler Messages, 60
  4356.         PCC Errors, 62
  4357.         PCC Fatal Errors, 60
  4358.         PCC Files, 9
  4359.  
  4360.  
  4361.  
  4362.  
  4363.         PCC Warnings, 66
  4364.         PCCA Assembler Messages, 67
  4365.         PCCA Errors ( from PCC Execution ), 67
  4366.         PCCL Messages, 71
  4367.         peek(), 46
  4368.         poke(), 47
  4369.         pow(), 47
  4370.         Preface, 7
  4371.         Preprocessor directives, 15
  4372.         Program Initialization, 28
  4373.         putc(), 47
  4374.         putchar(), 47
  4375.         puts(), 48
  4376.         putw(), 48
  4377.  
  4378.         Q
  4379.         qsort(), 48
  4380.  
  4381.         R
  4382.         RAM DISK, 11
  4383.         rand(), 49
  4384.         rename(), 49
  4385.         rindex(), 49
  4386.  
  4387.         S
  4388.         scanf(), 50
  4389.         scr_aputs(), 52
  4390.         scr_ci(), 52
  4391.         scr_clr(), 52
  4392.         scr_clrl(), 52
  4393.         scr_cls(), 53
  4394.         scr_co(), 52
  4395.         scr_csts(), 53
  4396.         scr_cursoff(), 53
  4397.         scr_curson(), 53
  4398.         scr_rowcol(), 53
  4399.         scr_scdn(), 54
  4400.         scr_scrdn(), 54
  4401.         scr_scrup(), 54
  4402.         scr_scup(), 54
  4403.         scr_setmode(), 54
  4404.         scr_setup(), 55
  4405.         scr_sinp(), 55
  4406.         setjmp(), 56
  4407.         Setting Up DOS 2.xx
  4408.            3.xx, ..., 10
  4409.         Space Considerations, 25
  4410.         sqrt(), 56
  4411.         srand(), 56
  4412.         sscanf(), 57
  4413.         Standard Library Functions, 34
  4414.         strcat(), 57
  4415.         strcmp(), 57
  4416.         strcpy(), 57
  4417.         Strings, 20
  4418.         strlen(), 58
  4419.         strncat(), 58
  4420.         strncmp(), 58
  4421.  
  4422.  
  4423.  
  4424.  
  4425.         strncpy(), 59
  4426.         Support Policy, 2
  4427.  
  4428.         T
  4429.         The PCCA 8088 Assembler, 21
  4430.         The PCCL Object File Linker, 23
  4431.         The C Language, 15
  4432.         The PCCS.S Standard Library, 28
  4433.         The Legal Stuff, 1
  4434.         times(), 59
  4435.         TRADEMARKS, 4
  4436.  
  4437.         U
  4438.         ungetc(), 59
  4439.         unlink(), 59
  4440.         Use by Educational Institutions, 5
  4441.         User Comments, 76
  4442.  
  4443.         W
  4444.         Warnings from PCCL, 71
  4445.  
  4446.         U
  4447.         Using Text
  4448.            Book, Magazine or Download source code, 8
  4449.  
  4450.